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About This Book 

This book teaches you all about the Java language and how to use it to create 
appletsand applications. By thetimeyou get through with thisbook, you’ll know 
enough about Java to do just about anything, inside an applet or out. 

Who Should Read This Book 

Thisbook is intended for people with at least some basic programming back- 
ground, which includes people with years of programming experience or people 
with only a small amount of experience. If you understand what variables, loops, 
and functions are, you’ll bejust finefor thisbook. T hesortsof peoplewho might 
want to read thisbook include you, if 

U You’re a real whiz at HTM L, understand CGI programming (in perl, 
AppleScript, Visual Basic, or some other popular CGI language) pretty 
well, and want to move on to the next level in Web page design. 

□ You had some Basic or Pascal in school and you have a basic grasp of 
what programming is, but you’ve heard J ava is easy to learn, really 
powerful, and very cool. 

n You’ve programmed C and C++ for many years, you’ve heard this Java 
thing is becoming really popular and you’re wondering what all thefuss 
is all about. 

□ You’ve heard that J ava is really good for W eb-based applets, and you’re 
curiousabout how good it isfor creating more general applications. 

W hat if you know programming, but you don’t know object-oriented program- 
ming? Fear not. Thisbook assumes no background in object-oriented design. If 
you know object-oriented programming, in fact, thefirst coupleof days will be 
easy for you. 

H ow T his B ook I s Structured 

T his book is intended to be read and absorbed over the course of three weeks. 
D uring each week, you’ll read seven chapters that present concepts related to the 
Java language and the creation of appletsand applications. 



Conventions 



Note: A N otebox presents interesting pieces of information related to the surround- 
ing discussion. 



n T echnical N ote: A T echnical N ote presents specific technical information related to 

\ the surrounding discussion. 

Tip: A Tip box offers advice or teaches an easier way to do something. 

Caution: A Caution box alerts you to a possible problem and gives you advice to 
avoid it. 

* Warning: A Warning box advises you about potential problems and helps you steer 
clear of disaster. 

NEW#' 

TERM N ew terms are introduced in N ew Term boxes, with the term in italics. 

[Type] A type icon identifies some new HTML code that you can type in yourself. 

jUjjjjjjj An Output icon highlightswhatthesameHTM L code looks like when viewed by 
1 — either N etscape or M osaic. 

j/yysis An analysis icon alertsyou to the author’s line-by-line analysis 
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I introduction 

The World Wide Web, for much of its existence, has been a method for distributing passive 
information to a widely distributed number of people. T heW eb has, indeed, been exceptionally 
good forthat purpose. W ith theaddition of formsand imagemaps, W eb pages began to become 
interactive— buttheinteraction wasoften simply anew way to getatthesameinformation.The 
limitationsof Web distribution were all too apparent once designers began to try to stretch the 
boundaries of what theW eb can do. Even other innovations, such as N etscape's server push to 
createdynamic animations, were merely cl ever tricks layered on top of aframework that wasn’t 
built to support much other than static documents with images and text. 

Enter Java, and the capability for Web pages of containing Java applets. Applets are small 
programsthatcreateanimations, multimediapresentations, real-time(video) games, multi-user 
networked games, and real interactivity— in fact, most anything a small program can do, J ava 
appletscan. D ownloaded overthenetand executed insideaW eb page by a browser that supports 
Java, applets are an enormous step beyond standard Web design. 

Thedisadvantageof Javaisthat to createj ava applets right now, you need to write them in the 
Java language. Java is a programming language, and as such, creating Java applets is more 
difficuItthancreatingaWebpageoraformusingHTM L. Soon therewill betoolsand programs 
that will make creating Java applets easier— theymaybeavailablebythetimeyou read this. For 
now, however, theonlywaytodelveintoj ava isto learn thelanguage and start playing with the 
raw Java code. Even when thetoolscomeout, you maywantto do more with Javathanthetools 
can provide, and you’re back to learning the language. 

That’swhereT each Yourself J ava in 21 Dayscomesin.Thisbookteachesyou all about thejava 
language and how to use it to create not only applets, but also applications, which are more 
general J ava programsthat don’t need to run insideaW eb browser. Bythetimeyou get through 
with thisbook, you’ll know enough aboutjavato do just about anything, inside an applet or 
out. 

Who Should Read This Book 

T each Yourself J ava in 21 Days is intended for people with at least some basic programming 
background— which includes people with years of programming experience and people with 
only a small amount of experience. If you understand what variables, loops, and functionsare, 
you’ll bejust finefor this book. T he sorts of people who might want to read this book include 
you, if one or more of the following is true: 

□ You’re a real whizatHTM L, understand CGI programming (in perl, AppleScript, 
Visual Basic, or some other popular CGI language) pretty well, and want to move 
onto the next level in Web page design. 
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□ You had some Basic or Pascal in school, you’ve got a basic grasp of what programming 
is, but you’ve heard J ava is easy to learn, really powerful, and very cool. 

□ You’ve programmed C and C -H-for many years, you’ve heard thisj ava thing is 
becoming really popular, and you’re wondering what all the fuss is all about. 

□ You’ve heard that Java is really good for Web-based applets, and you’re curious about 
how good it is for creating more general applications. 

What if you know programming, but you don’t know object-oriented programming? Fear not. 
Teach Y ourself Java in 21 Daysassumesno background in object-oriented design. If you know 
object-oriented programming, the first couple of days will be easy for you. 

What if you’rearankbeginner?Thisbook might movealittlefastforyou.Javaisagood language 
to start with, though, and if you take it slow and work through all the examples, you may still 
beableto pick upjavaand start creating your own applets. 

H ow T his B ook I s O rganized 

T each Y ourself Java in 21 DaysdescribesJ ava primarily in its current state— what’s known asthe 
beta API (Application Programming Interface). This is the version of Java that N etscapeand 
other browsers, such as Spyglass's M osaic, support. A previous version of Java, thealpha API , 
was significantly different from theversion described in thisbook, and thetwoversionsarenot 
compatiblewith each other.There are other books that descri be only thealpha API , and there 
may still be programs and browsers out there that can only run using alpha Java programs. 

Teach You rsalf Java in 21 Days uses primarilyj ava beta because that isthe version that is most 
current and isthe version that will continueto beused in thefuture. The alpha API isobsolete 
and will eventually dieout. If you learn J ava using beta API , you’ll be much better prepared for 
any future changes (which will be minor) than if you have to worry about both API sat once. 

J ava isstill in development. "Beta” meansthat J ava isnot complete and that thingsmay change 
between thetimethisbook isbeing written and thetimeyou read this. Keep thisin mind asyou 
work withj ava and with thesoftwareyou’ll useto create and compile programs. If things aren't 
behaving the way you expect, check theWeb sites mentioned at theend of this introduction for 
more information. 

T each You rselfj ava in 21 D ayscoversthej ava language and itsdasslibrariesin 21 days, organized 
as three separate weeks. Each week covers a different broad area of developing Java applets and 
applications. 

In the first week, you’ll learn about thejava language itself: 

_ Day 1 isthe basic introduction: what Java is, why it’s cool, and howto get the 
software. You'll also create your first Java applications and applets. 
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□ On Day 2, you’ll explore basic object-oriented programming concepts as they apply to 
Java. 

3 On Day 3, you start getting down to details with the basic Java building blocks: data 
types, variables, and expressions such as arithmetic and comparisons. 

(O D ay 4 goes into detail about how to deal with objects in J ava: how to create them, 
how to access their variables and call their methods, and how to compare and copy 
them. You’ll also get your first glance at thej ava class libraries. 

□ On Day 5, you’ll learn more about J ava with arrays, conditional statements, and 
loops. 

O Day 6 is the best one yet. You’ll learn how to create classes, the basic building blocks 
of any Java program, as well as how to put together aj ava application (an application 
being a Java program that can run on its own without a Web browser). 

P Day 7 builds on what you learned on Day 6. On Day 7, you’ll learn more about how 
to create and use methods, including overriding and overloading methods and 
creating constructors. 

Week 2 is dedicated to applets and thej ava class libraries: 

n Day 8 provides the basics of applets- how they’re different from applications, how to 
create them, and the most important parts of an applet’s life cycle. You’ll also learn 
how to create HTML pages that contain J ava applets. 

□ On Day 9, you’ll learn about thej ava classes for drawing shapes and characters to the 
screen— in black, white, or any other color. 

n On Day 10, you'll start animating those shapes you learned about on Day 9, includ- 
ing learning what threads and their uses are. 

n Day 11 covers more detail about animation, adding bitmap images and audio to the 
soup. 

Day 12 delves into interactivity— handling mouse and keyboard clicks from the user 
in your Java applets. 

n Day 13 is ambitious; on that day you’ll learn about using Java's Abstract Windowing 
T oolkitto create a user interface in your applet including menus, buttons, checkboxes, 
and other elements. 

I On Day 14, you explorethe last of the main J ava class librariesfor creating applets: 
windows and dialogs, networking, and a few other tidbits. 

Week 3 finishesup with advanced topics, for when you start doing larger and more complexj ava 
programs, or when you want to learn more: 

0 n D ay 15, you’ll learn more about the J ava language’s modifiers- for abstract and 
final methods and classes as well as for protecting a class’s private information from 
the prying eyes of other classes. 
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□ Day 16 covers interfaces and packages, useful for abstracting protocols of methods to 
aid reuse and for the grouping and categorization of classes. 

Z D ay 17 covers exceptions: errors and warnings and other abnormal conditions, 
generated either by the system or by you in your programs. 

□ Day 18 builds on the thread basics you learned on Day 10 to give a broad overview of 
multithreading and how to use it to allow different parts of your Java programs to run 
in parallel. 

□ On Day 19, you’ll learn all about the input and output streams in Java’s I/O library. 

□ Day 20 teaches you about native code- how to linkC code into yourjava programs 
to provide missing functionality or to gain performance. 

□ Finally, on Day 21, you’ll get an overview of some of the "behind-the-scenes” techni- 
cal details of how Java works: the bytecode compiler and interpreter, the techniques 

J ava uses to ensure the i ntegrity and security of your programs, and the J ava garbage 
collector. 

Conventions Used in This Book 

T ext that you type and text that should appear on your screen is presented in monospace type: 

It will look like this. 

to mimictheway text lookson your screen. Variables and placeholderswill appear inmonospace 

italic. 

T he end of each chapter offers common questions asked about that day’s subject matter with 
answers from the authors. 

Web Sites for Further Information 

Before, while, and after you read this book, there are two Web sites that may be of interest to 
you as aj ava developer. 

The official Java web site is at http://java.sun.com/. At this site, you’ll find the Java 
development software, the H otj ava web browser, and online documentation for all aspects of 
thej ava language. 1 1 has several mirror sitesthat it lists online, and you should probably usethe 
site "closest” to you on thel nternet for your downloading and Java Web browsing. Thereisal so 
a site for developer resources, called Gamelan, at http://www.gameian.com/. 

This book also has a companion Web site at http://www.me.com/web/java/. Information at 
that siteindudes examples, moreinformationand background for thisbook, correctionsto this 
book, and other tidbits that were not included here. 
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H elloand welcometoT each Yourself Java in 21 D ays! Starting today and forthenextthreeweeks 
you’ll learn all about thejava language and how to useitto createapplets,aswellashowto create 
stand-alonejava applications that you can use for just about anything. 

NEW*' An applet isadynamic and interactive program that can run insideaWeb pagedisplayed 
TERM by a j ava-capable browser such as H otj ava or N etscape 2.0. 

TheH otjava browser isa World Wide Web browser used to view Web pages, follow links, and 
submit forms. It can also download and play applets on the reader's system. 

That’s the overall goal forthenextthreeweeks. T oday, the goals are somewhat more modest, 
and you’ll learn about the following: 

Z W hat exactly J ava and H otj ava are, and their current status 
_ W hy you should learn J ava— its various features and advantages over other program- 
ming languages 

□ Getting started programming in Java— what you’ll need in terms of software and 
background, as well as some basic terminology 

□ H ow to create your first J ava programs- to close this day, you’ll create both a simple 
Java application and a simple Java applet! 

What IsJ ava? 

Javaisan object-oriented programming language developed bySun M icrosystems, acompany 
best known for its high-end U nix workstations. M odeled after C ++, thejava language was 
designed to be small, simple, and portable across platforms and operating systems, both at the 
source and at the binary level (more about this later). 

J ava is often mentioned in the same breath as H otj ava, a W orld W ide W eb browser from Sun 
like N etscape or M osaic (see Figure 1.1). What makes H otjava different from most other 
browsers is that, in addition to all its basic Web features, it can also download and play applets 
on the reader's system. Applets appear in a Web page much in the same way as images do, but 
unlike images, applets are dynamic and interactive. Applets can be used to create animations, 
figures, or areas that can respond to input from thereader, games, or other interactive effects on 
the same W eb pages among the text and graphics. 

Although H otj ava was the first World WideWeb browser to beableto playj ava applets, Java 
support israpidly becomingavailablein other browsers. N etscape2.0 provides support for Java 
applets, and other browser developers have also announced support for J ava in forthcoming 
products. 
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Figure 1.1. 

TheH otjava browar. 




T o create an applet, you writeit in thej avalanguage, compileit using aj ava compiler, and refer 
to that applet in your H T M L W eb pages. You put theresulting H T M L and J avafileson a W eb 
sitemuchinthesamewaythatyou makeordinaryHTM L and imagefi lesavai lable. Then, when 
someone using the H otj ava browser (or other J ava-aware browser) views your page with the 
embedded applet, that browser downloads the applet to the local system and executes it, and 
then the reader can view and interact with your applet in all its glory (readers using other 
browsers won’t see anything). You’ll learn more about how applets, browsers, and the World 
Wide Web work together further on in this book. 

T he important thing to understand about J ava is that you can do so much more with it besides 
create applets. Java was written as a full-fledged programming language in which you can 
accomplish the same sorts of tasks and solve the same sorts of problems that you can in other 
programming languages, such asC orC ++. H otj avaitself, including all the networking, display, 
and user interface elements, iswritten in Java. 
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Java's Past, Present, and Future 

Thejava language was developed at Sun M icrosystemsin 1991 as part of a research project to 
develop software for consumer electronics devices- television sets, VCRs, toasters, and the 
other sorts of machines you can buy at any department store. J ava’s goals at that time were to 
be small, fast, efficient, and easily portabletoawiderangeof hardwaredevices. Itisthosesame 
goalsthat madej avaan ideal languagefor distributing executableprogramsviatheW orld W ide 
Web, and al so a general-purpose programming languagefor developing programsthat are easily 
usable and portable across different platforms. 

Thejavalanguagewasused in several projectswithin Sun, butdid not get very much commercial 
attention until it was paired with H otjava. H otjava was written in 1994 in a matter of months, 
both as a vehicle for downloading and running applets and also as an example of the sort of 
complex application that can be written in Java. 

Atthetimethisbook is being written, Sun has released the beta version of thejava Developer’s 
Kit (JDK), which includes tools for developing Java applets and applications on Sun systems 
running Solaris2.3 or higher for W indowsN T and for W indows95. By thetimeyou read this, 
support for J ava development may have appeared on other platforms, either from Sun or from 
third-party companies. 

N otethat because thej D K iscurrentlyin beta, itisstill subject to changebetween nowand when 
it isoffi dally released. Appletsandapplicationsyou writeusing theJDK and using theexamples 
in this book may require some changes to work with future versions of theJD K. H owever, 
becausethej ava language has been around forseveral yearsand has been used for several projects, 
the language itself is quite stable and robust and most likely will not change excessively. Keep 
this beta status in mind as you read through this book and as you develop your own Java 
programs. 

Support for playing J ava programs is a little more confusing at the moment. Sun’s H otj ava is 
not currently included with theBetaJ D K; theonly availableversion ofH otjavaisan older alpha 
version, and, tragically, applets written for the alpha version ofjavado not work with the beta 
J D K, and viceversa. By thetimeyou read this, Sun may have released anewer version of H otj ava 
which will enable you to view applets. 

T hej D K doesindudean application called appletviewerthatallowsyou to test yourj ava applets 
as you write them. If an applet works in theappletviewer, it should work with anyjava-capable 
browser. You’ll learn more about applet viewer later today. 

What’sin store for the future? In addition to the final Java release from Sun, other companies 
have announced support for J ava in their own W orld W ide W eb browsers. N etscapeC ommu- 
nicationsCorporation hasalready incorporated J ava capabilitiesinto the2.0 version of theirvery 
popular N etscape N avi gator W eb browser— pages with embedded J ava applets can be viewed 
and played with N etscape. With support forj ava available in as popular a browser as N etscape, 



toolsto help develop J avaapplications(debuggers, development environments, and so on) most 
likely will be rapidly available as well. 



Why Learn J ava? 




At the moment, probably the most compelling reason to learn J ava- and probably the reason 
you bought thisbook— isthat H otjavaappletsarewritten in Java. Even ifthatwerenotthecase, 
Java as a language has significant advantages ova otha languages and other programming 
environmentsthat make it suitablefor just about any programming task. T hissection describes 
some of those advantages. 



J ava I s P latfor m-l ndependent 

Platform independence is one of the most significant advantages that Java has ova other 
programming languages, particularlyforsystemsthat need to work on many diffaent platforms. 
Java is platform-independent at both the source and the binary level. 

NEW** Platform-independence is a program's capability of moving easily from one computa 
TERM system to another. 

At the source level, Java’s primitive data types have consistent sizes across all development 
platforms. Java’sfoundation class libraries make it easy to write code that can be moved from 
platform to platform without the need to rewrite it to work with that platform. 

Platform-independence doesn't stop at the source level, howeva. Java binary files are also 
platform-independent and can run on multiple problems without the need to recompile the 
source. H ow does this work?J ava binary files are actually in a form called bytecodes. 

NEW«~ Bytecodesareasetof instructions that looksalotlikesomemachinecodes, but that isnot 
TERM specific to any one processor. 

N ormally, when you compile a program written in C or in most other languages, thecompila 
translates your program into machine codes or processor instructions. T hose instructions are 
specific to the processor your computa is running- so, for example, if you compileyourcode 
on aPentium system, theresulting program will run only on otha Pentium systems. If you want 
to use the same program on anotha system, you have to go back to your original source, get a 
compila for that system, and recompile your code. Figure 1.2 shows the result of this system: 
multiple executable programs for multiple systems. 

T hings arediffaent when you write code in J ava. T hej ava development environment has two 
parts: a J ava compi ler and a J ava i ntapreter. T he J ava compi ler takes your J ava program and 
instead of genaating machine codes from your source files, it generates bytecodes. 
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Figure 1.2. 

T raditional compiled 
programs 



Binary File 
(Pentium) 




Compiler (SPARC) 



T o run ajava program, you run a program called a bytecode interpreter, which in turn executes 
yourj avaprogram (seeF igurel.3). You can eitherrun theinterpreter byitself, or — forapplets — 
thereisa bytecodeinterpreter built into H otjavaand other Java-capable browsers that runsthe 
applet for you. 




W hy go through all the trouble of adding this extra layer of the bytecode interpreter? H aving 
yourjavaprogramsinbytecodeformmeansthat instead of beingspecifictoanyonesystem, your 
programs can be run on any platform and any operating or window system as long asthej ava 
interpreter is available. T his capability of a single binary file to be executable across platforms 
iscrucial to what enables applets to work, because theW orld W ideW eb itself isalso platform- 
independent. J ust asH T M L filescan beread on any platform, so appletscan beexecuted on any 
platform that is a Java-capable browser. 

The disadvantage of using bytecodes is in execution speed. Because system-specific programs 
run directly on the hard ware for which they arecompiled, they run significantly faster than Java 
bytecodes, which must be processed by the interpreter. F or manyj ava programs, the speed may 
not bean issue. If you writeprogramsthatrequiremoreexecution speed than thej ava interpreter 
can provide, you have several solutionsavailableto you, including being ableto link native code 
into yourj ava program or using toolsto convert yourj ava bytecodesinto native code. N otethat 
byusinganyofthesesolutions,you lose the portability that J ava bytecodes provide. You’ll learn 
about each of these mechanisms on D ay 20. 

J ava I s O bject-O riented 

To some, object-oriented programming (OOP) technique is merely a way of organizing 
programs, and it can be accompli shed using any language. Working with areal object-oriented 
language and programmingenvironment, however, enablesyou totakefull advantageof object- 
oriented methodology and its capabilities of creating flexible, modular programs and reusing 
code. 

M any of Java’s object-oriented concepts are inherited from C++, the language on which it is 
based, but it borrows many concepts from other object-oriented languages as well. Likemost 
object-oriented programming languages, J ava includesa set of class libraries that provide basic 
datatypes, system input and output capabilities, and other utility functions T hesebasic classes 
are part of the J ava development kit, which also has classes to support networking, common 
Internet protocols, and user interface tool kit functions. Because thesedasslibraries are written 
in J ava, they are portable across platforms as all J ava applications are. 

You’ll learn more about object-oriented programming and Java tomorrow. 

J ava I s E asy to Learn 

In addition to its portability and object-orientation, oneof Java’sinitial design goalswasto be 
small and simple, and therefore easier to write, easier to compile, easier to debug, and, best of 
all, easy to learn. Keeping the language small also makesit more robust because there are fewer 
chancesforprogrammersto makedifficult-to-find mistakes. Despiteits size and simpledesign, 
however, Java still has a great deal of power and flexibility. 
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Java is modeled after C and C++, and much of the syntax and object-oriented structure is 
borrowed from the latter. If you are familiar with C ++, learning Java will be particularly easy for 
you, because you have most of the foundation already. 

Although J ava looks similar to C and C ++, most of the more complex parts of those languages 
have been excluded from Java, making the language simpler without sacrificing much of its 
power. There are no pointers in Java, nor isthere pointer arithmetic. Strings and arrays are real 
objects in Java. M emory management is automatic. To an experienced programmer, these 
omissions may be difficult to get used to, but to beginners or programmers who have worked 
in other languages, they make thej ava language far easier to learn. 

Getting Started with 
Programming in Java 

Enough background! Let’sfinish off this day by creating two real Java programs: a stand-alone 
J ava application and an applet that you can view in either in the appletvi ewer (part of thej D K) 
orin ajava-capable browser. Although both theseprogramsareextremely simple, they will give 
you an idea of what aj ava program looks like and how to compile and run it. 



Getting the Software 

In order to writej ava programs, you will, of course, need aj ava development environment. At 
thetime this book is being written, Sun’sJ ava D evelopment K it provides everything you need 
to start writingj ava programs. TheJDK isavailablefor Sun SPARC systemsrunningSolaris2.2 
or higher and for Windows NT and Windows 95. You can get the] DK from several places: 

Z The CD -ROM that came with this book contains the full JD K distribution. Seethe 
CD information for installation instructions. 

Z TheJDK can bedownloaded from Sun’sJavaFTP site at ftp: //java, sun.com/pub/ or 
from a mirror site (ftp: //WWW. blackdown.org/pub/Java/pub/is one). 



Note: Thej ava Development Kit is currently in beta release. Bythe time you read 
this, T he J D K may be available for other platforms, or other organizations may be 
selling J ava development tools as well. 
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Although N etscape and other J ava-aware browsers provide an environment for playing J ava 
applets, they do not provide a mechanism for developing Java applications. For that, you need 
separate tools- merely having a browser is not enough. 



Applets and Applications 

Java applications fall into two main groups: applets and applications. 

Applets, asyou have learned, arej ava programsthat aredownloaded over theW orld W ideW eb 
and executed by a W eb browser on the reader’s machine. Applets depend on a J ava-capable 
browser in order to run (although they can also be viewed using a tool called theappletviewer, 
which you’ll learn about later today). 

JavaapplicationsaremoregeneralprogramswrittenintheJavalanguage.Javaapplicationsdon’t 
requirea browser to run, and in fact, Java can beused to createmost other kindsof applications 
that you would normally use a more conventional programming language to create. H otjava 
itself is aj ava application. 

A singlej ava program can bean applet or an application or both, depending on how you write 
that program and the capabilities that program uses. Throughout this first week, you’ll be 
writing mostly H otj ava applications; then you’ll apply what you've learned to write applets in 
Week 2. If you’re eager to get started with applets, be patient. Everything that you learn while 
you’recreatingsimplej ava applicationswill apply to creating applets, and it’seasier to start with 
the basics before moving onto the hard stuff. You’ll be creating plenty of applets in W eek 2. 



Creating a J ava Application 

Let'sstart by creating asimplej ava application: thedassicH elloW orld examplethat all language 
books use to begin. 

Aswith all programming languages, your Java source files are created in a plain text editor, or 
in an editor that can save files in plain ASCII without any formatting characters. On U nix, 
emacs, ped, or vi will work; on W indows, N otepad or D 0 S Edit are both text editors. 

Fire up your editor of choice, and enter the Java program shown in Listing 1.1. T ype this 
program, as shown, in your text editor. Be careful that all the parentheses, braces, and quotes 
are there. 



Listing 1.1. Your first Java application. 

1: class HelloWorld { 

2: public static void main (String args[]) { 

3: System.out.println( "Hello World!"); 
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% 

W Warning: The numbers before each line are part of the listing and not part of the 

# program; they’re there so I can refer to specific line numbers when I explain what’s 

L going on in the program. Do not include them in your own file. 



This program has two main parts: 

™ G3 All the program is enclosed in a class definition— here, a class called Heiioworid. 
Z T he body of the program (here, just the one line) is contained in a routine called 
main (). In Java applications, as in a C or C++ program, main o is the first 
routine that is run when the program is executed. 

You’ll learn more about both these parts of a Java application as the book progresses. 

Once you finish typing the program, savethefile. Conventionally, Java source files are named 
thesamenameasthedassthey define, with an extension of . j ava. T hisfileshould therefore be 
called Heiioworid. java. 

Now, let’scompile the source fileusing thejava compiler. In Sun’sJDK, thej ava compiler is 
Called javac. 

TocompileyourJ ava program, M akesurethejavac program isin your execution path and type 
javac followed by the name of your source file: 

javac Heiioworid. java 



Note: In these examples, and in all the examples throughout this book, we’ll be 
using Sun’sJ ava compiler, part of theJD K. Ifyou have a third-party development 
environment, check with the documentation for that program to see how to 
compile your Java programs. 



The compiler should compile the file without any errors. Ifyou get errors, go back and make 
sure that you’ve typed the program exactly as it appears in Listing 1.1. 

When the program compileswithout errors, you end up with afilecalled H eiloWorld.dass, in 
the same directory as your source file. This is your Java bytecode file. You can then run that 
bytecodefile using thejava interpreter. In thej D K, thejava interpreter is called simplyjava. 
M akesurethejava program isin your path and type j ava followed by thenameofthefilewithout 
the .class extension: 

java Heiioworid 



12 



If your program was typed and compiled correctly, you should get the string "Heiio world!" 
printed to your screen as a response. 



N ote: Remember, thej ava compiler and thej ava interpreter are different things. 
You use thej ava compiler (javac) for your Java source files to create .class files, and 
you use thej ava interpreter (java)to actually run your class files. 



Creating a J ava Applet 

Creatingappletsisdifferentfrom creatingasimpleapplication,becauseJavaappletsrunandare 
displayed insidea W eb pagewith other pageelementsand as such havespecial rulesfor how they 
behave. Because of these special rulesfor applets in many cases (particularly the simple ones), 
creating an applet may be more complex than creating an application. 

For example, to do asimpleH ello World applet, instead of merely being ableto print a message, 
you have to create an applet to make space for your message and then use graphics operations 
to paint the message to the screen. 



N ote: Actually, if you run the H ello W orld application as an applet, the Heiio 
world message prints to a special window or to a log file, depending on how the 
browser has screen messages set up. It will not appear on the screen unless you 
write your applet to put it there. 



I n thenext example, you createthat simple H ello W orld applet, placeit insidea W eb page, and 
view the result. 

First, you set up an environment so that your Java-capable browser can find your H TM L files 
and your applets. M uch of thetime, you’ll keep your FI TM L files and your applet code in the 
same directory. Although this isn't required, it makes it easier to keep track of each element. I n 
thisexample, you use a directory called FH T M L that contains all the files you’ll need. 

mkdir HTML 

N ow, open up that text editor and enter Listing 1.2. 




import java.awt. Graphics; 

class HelloWorldApplet extends java. applet. Applet { 




ES. 



5: public void paint (Graphics g) { 

6: g. drawstring (“Hello world!", 5, 25); 

7: > 

8 :} 



Save that file inside your html directory. Just like with Java applications, give your file a name 
thathasthesamenameasthedass. lnthiscase,thefilenamewouldbeHeiioworidAppiet.java. 

Features to note about applets? There are a couple I’d like to point out: 

Z The import lineatthetopofthefileissomewhatanalogoustoan #inciude statement 
in C; it enables this applet to interact with theJDK classes for creating applets and for 
drawing graphics on the screen. 

Z The paint o method displays the content of the applet onto the screen. H ere, the 
string Heiio world gets drawn. Applets use several standard methods to take the place 
of maino, which include imt ( ) to initialize the applet, starto to start it running, 
and paint o to display it to the screen. You’ll learn about all of these in Week 2. 

Now, compile the applet just as you did the application, using javac, thejava compiler. 

javac HelloWorldApplet. java 

Again, just asfor applications, you should now haveafilecalled H elloW orldApplet.classin your 
HTML directory. 

T o include an applet in a Web page, you refer to that applet in theHTM L code for that Web 
page. H ere, you create a very simple HTM L file in theHTM L directory (see Listing 1.3). 

Type 

1: <HTML> 

2: <HEAD> 

3: <TITLE>Hello to Everyone ! </TITLE> 

4: </HEAD><BODY> 

5: <P>My Java applet says: 

6: <APPLET CODE="HelloWorldApplet . Class" WIDTH=150 HEIGHT=25> 

7: </BODY> 

8: </HTML> 
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You refer to an applet in yourHTM L files with the<APPLET> tag. You’ll learn more about 
<applet> later on, but here are two things to note: 

U se the code attribute to indicate the name of the class that contains your applet. 
UsethewiDTH and height attributes to indicate the size of the applet. The browser uses 
these values to know how big a chunk of space to leave for the applet on the page. 

H ere, a box 150 pixels wide and 25 pixels high is created. 

SavetheHTM L filein your H T M L directory, with adescriptivenameffor example, you might 
name your HTM L file the same name as your applet— H ellowWorldApplet.html). 

And now, you’re ready for thefinal test— actually viewing theresult of your applet. To view the 
applet, you need one of the following: 

ip A browser that supportsj ava applets, such as N etscape 2.0. 

[□. f he appletviewer application, which is part of thej D K . T he appletviewer is not a 
Web browser and won’t enable you to see the entire Web page, but it’s acceptable for 
testing to see how an applet will look and behave if there is nothing else available. 




Note: Do not use the alpha version of H otjavato view your applets; applets 
developed with the beta JD K and onward cannot be viewed by the alpha H otj ava. 

I f, by the time you read this, there is a more recent version of H otj ava, you can use 
that one instead. 



Ifyou’reusingaJava-capablebrowsersuchasN etscape to view your applet files, you can usethe 
Open Local... item under the File menu to navigate to theHTM L file containing the applet 
(make sure you open theHTM L file and not the class file). You don't need to install anything 
on a W eb server yet; all this works on your local system. 

If you don’t haveaW eb browser with J ava capabilitiesbuilt into it, you can usetheappletviewer 
program to view your J ava applet. T o run appletviewer, just indicate the path to theH T M L file 
on the command line: 

appletviewer HTML/HelloWorldApplet . html 
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Tip: Although you can start appletviewer from the same directory as your HTML 
and class files, you may not be able to reload that applet without quitting 
appletviewer first. If you start appletviewer from some other directory (as in the 
previous command line), you can modify and recompileyourjava applets and then 
just usethe Reload menu item to view the newer version. 
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N ow, if you use the browser to view theapplet, you see something similar to the image shown 
in Figure 1.4. If you’re using appletviewer, you won’t see the text around the applet (wiy java 
applet says. ..), but you will seethe Hello World itself. 

Figure 1.4. 

T he H ello World applet. 



My Java Applet says: H ello world ! 



Summary 

T oday, you got a basic introduction to thej ava language and its goals and features. J ava is a 
programmi ng language, similarto C or C ++, i n which you can develop a widerangeof programs. 
T he most common use of J ava at the moment is in creating applets for H otj ava, an advanced 
W orld W ideW eb browser also written in J ava. Applets arej ava programs that aredownloaded 
and run as part of aW eb page. Applets can createanimations, games, interactive programs, and 
other multimedia effects on W eb pages. 

Java’s strengths lie in its portability— both at the source and at the binary level, in its object- 
oriented design- and in its simplicity. Each of these features help make applets possible, but 
they also makej ava an excellent language for writing more general-purpose programs that do 
not requireH otj avaor otherj ava-capable browser to run. T hesegeneral-purposej ava programs 
are called applications. H otj ava itself is a Java application. 

To end thisday, you experimented with an exampleapplet and an exampleapplication, getting 
a feel for thedifferences between thetwoand how to create, compile, and run Java programs- 
or, in the case of applets, how to include them in Web pages. From here, you now have the 
foundation to create more complex applications and applets. 

Q&A 

Q I'd like to use H otj ava as my regular Web browser. You haven't mentioned much 
about H otj ava today. 

A The focus of this book isprimarily on programming injavaand in the FI otj ava 
classes, rather than on using FI otj ava itself. D ocumentation for using the FI otj ava 
browser comes with the FI otj ava package. 

Q I know a lot about FITM L, but not much about computer programming. Can I 
still write Java programs? 
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A If you have no programming experience whatsoever, you most likely will find pro- 
gramming J ava significantly more difficult. H owever, J ava is an excellent language to 
learn programming with, and if you patiently work through the examples and the 
exercises in this book, you should be able to learn enough to get started with Java. 

Q According to today's lesson, Java applets are downloaded via H otjava and run on 
the reader's system. Isn't that an enormous security hole? What stops someone 
from writing an applet that compromises the security of my system- or worse, 
that damages my system? 

A Sun’sJ ava team has thought a great deal about the security of applets within Java- 
capable browsers and has implemented several checks to make sure applets cannot do 
nasty things: 

□ J ava applets cannot read or write to the disk on the local system. 

ID J ava applets cannot execute any programs on the local system. 

P J ava applets cannot connect to any machines on the W eb except for the server 
from which they are originally downloaded. 

I n addition, thej ava compiler and interpreter check both the J ava source code and the 
J ava bytecodes to make sure that the J ava programmer has not tried any sneaky tricks 
(for example, overrunning buffers or stack frames). 

T hese checks obviously cannot stop every potential security hole, but they can 
significantly reduce the potential for hostile applets. You’ll learn more about security 
issues later on in this book. 

Q I followed all the directions you gave for creating a Java applet. I loaded it into 
H otjava, but Heiio world didn't show up. What did I do wrong? 

A I’ll bet you’re using the alpha version of H otjava to view the applet. Unfortunately, 
between alpha and beta, significant changes were made as to how applets are written. 
The result is that you can't view beta applets (as this one was) in the alpha version of 
H otjava, nor can you view alpha applets in browsers that expect beta applets. To view 
the applet, either use a different browser, or usetheappletviewer application that 
comes with theJDK. 
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0 bject-oriented programming (0 0 P) is one of the bigger programming buzzwords of recent 
years, and you can spend yearslearning all about object-oriented programming methodologies 
and how they can make your life easier than T heO Id W ay of programming. It all comesdown 
to organizing your programs in ways that echo how things are put together in the real world. 

T oday, you’ll get an overview of object-oriented programming concepts in J ava and how they 
relate to how you structure your own programs: 

fit.' W hat classes and objects are, and how they relate to each other 
Z The two main parts of a class or object: its behaviors and its attributes 

□ Class inheritance and how inheritance affects the way you design your programs 

□ Some information about packages and interfaces 

If you’re already familiarwith object-oriented programming, much of today’slesson will beold 
hat to you. You may want to skim it and go to a m ovie tod ay instead. T omorrow, you’ll get into 
more specific details. 

Thinking in Objects: An Analogy 

Consider, if you will, Legos. Legos, for those who do not spend much timewith children, are 
small plastic building blocks in various colors and sizes. They have small round bits on oneside 
that fit into small round holes on other Legos so that they fit together snugly to create larger 
shapes. W ith different Lego bits(Lego wheels, Lego engines, Lego hinges, Lego pulleys), you can 
put together castles, automobiles, giant robotsthat swallow cities, orjust about anything el seyou 
can create. Each Lego bit isasmall object that fitstogether with other small objectsin predefined 
ways to create other larger objects. 

H ere'sanother example. You can walk into a computer store and, with a little background and 
often some help, assemble an entire PC computer system from various components: a 
motherboard, a CPU chip, a video card, a hard disk, a keyboard, and so on. Ideally, when you 
finish assembling all the various self-contained units, you haveasystem in which all theunits 
work together to createa larger system with which you can solve theproblemsyou bought the 
computer for in the first place. 

Internally, each of those components may be vastly complicated and engineered by different 
companieswith different methodsof design. But you don't need to know how the component 
works, what every chip on the board does, or how, when you press the A key, an "A” gets sent 
to your computer. As the assembler of the overall system, each component you use is a self- 
contained unit, and all you are interested in is how the units interact with each other. Will this 
video card fit into the slots on the motherboard and will thismonitor work with thisvideo card? 
Will each particular component speak the right commandsto theother components it interacts 
with so that each part of the computer is understood by every other part? 0 nee you know what 



the interactions are between the components and can match the interactions, putting together 
the overall system is easy. 

What does this have to do with programming? Everything. Object-oriented programming 
works in exactly this same way. Using object-oriented programming, your overall program is 
made up of lots of different self-contained components (objects), each of which has a specific 
role in the program and all of which can talk to each other in predefined ways. 

O bjects and C lasses 

0 bject-oriented programming ismodeled on how, in thereal world, objects are often madeup 
of many kindsof smaller objects. Thiscapability of combining objects, however, isonlyonevery 
general aspect of object-oriented programming. 0 bject-oriented programming providesseveral 
other concepts and featuresto make creating and using objects easier and more flexible, and the 
most important of these features is that of classes. 

NEW** A class ' s a template for multiple objects with similar features. Classes embody all the 
TERM featu res of a parti cu I ar set of obj ects. 

When you writea program in an object-oriented language, you don’t defineactual objects. You 
define classes of objects. 

F or example, you might have a Tree class that descri bes the features of all trees (has leaves and 
roots, grows, creates chlorophyll). Themee cl ass serves as an abstract model fortheconcept of 
a tree— to reach out and grab, or interact with, or cut down a tree you have to have a concrete 
instance of that tree. Of course, once you have a tree class, you can create lots of different 
instances of that tree, and each different tree instance can have different features (short, tall, 
bushy, drops leaves in Autumn), while still behaving like and being immediately recognizable 
as a tree (see Figure 2.1). 

NEW«~ An instance of a class is another word for an actual object. If classes are an abstract 
TERM representation of an object, an instance is its concrete representation. 

So what, precisely, isthe difference between an instance and an object? N othing, really. Object 
isthemoregeneral term, but both instancesand objectsaretheconcreterepresentation of adass. 

1 n fact, the terms instance and object are often used interchangeably in 0 0 P language. An 
instance of a tree and a tree object are both the same thing. 

Inanexampledoserto thesort of thingsyou might want to do in Java programming, you might 
createaclassfortheuser interface element called a button. TheButton class defines thefeatures 
of a button (its label, its size, its appearance) and how it behaves (does it need a single click or 
a double click to activate it, does it change color when it’s clicked, what does it do when it’s 
activated?). Once you define the Button class, you can then easily create instances of that 
button- that is, button objects- that all takeon the basic features of the button asdefined by 
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the class, but may have different appearances and behavior based on what you want that 
particular button to do. By creating a Button class, you don’t have to keep rewriting the code 
for each individual button you want to use in your program, and you can reuse theButton class 
to create different kinds of buttons as you neaf them in thisprogram and in other programs. 



Figure 2.1. 

The tree das and 
tree instances 




Tip: If you’re used to programming in C, you can think of a class as sort of 
creating a new composite data type by using struct and typedet . C lasses, how- 
ever, can provide much more than just a collection of data, as you’ll discover in the 
rest of today’s lesson. 

When you write a Java program, you design and construct a set of classes. T hen, when your 
program runs, in stances of those cl asses are created and discarded as needed. Your task, asajava 
programmer, is to create the right set of classes to accomplish what your program needs to 
accomplish. 
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Fortunately, you don’t haveto start from thevery beginning: thej ava environment comeswith 
a library of classes that implement a lot of the basic behavior you need- not only for basic 
programming tasks (cl asses to provide basic math functions, arrays, strings, and so on), but also 
for graphics and networking behavior. In many cases, thej ava class libraries may be enough so 
that all you haveto do in your Java program is create a single class that uses the standard class 
libraries. For complicated J ava programs, you may have to create a whole set of classes with 
defined interactions between them. 

NEW** A class library is a set of classes. 

TERM 

Behavior and Attributes 

Every cl ass you write in J ava is generally made up of two components: attributes and behavior. 

I n this section, you’ll learn about each one as it applies to a thoeretical class called Motorcycle. 
T o finish up this section, you’ll create the Java code to implement a representation of a 
motorcycle. 

Attributes 

Attributes aretheindividualthingsthatdifferentiateoneobject from another and determinethe 
appearance, state, or other qualities of that object. Let's create a theoretical class called 
Motorcycle. T he attributes of a motorcycle might include the following: 

□ Color: red, green, silver, brown 
®f Style: cruiser, sport bike, standard 

□ M ake: Honda, BMW, Bultaco 

Attributes of an object can also include information about its state; for example, you could have 
features for engine condition (off or on) or current gear selected. 

Attributes are defined by variables; in fact, you can consider them analogousto global variables 
for the entire object. Because each instance of a class can havedifferent valuesfor its variables, 
each variable is called an instance variable. 

NEW«~ I nstancevariablesdefinetheattributesof an object. T heclassdefinesthekind of attribute, 
TERM and each instance stores its own value for that attribute. 

Each attribute, as the term isused here, hasa singlecorresponding instance variable; changing 
the value of a variable changes the attribute of that object. I nstance variables may be set when 
an object is created and stay constant throughout the life of the object, or they may be able to 
change at will as the program runs. 
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I n addition to instance variables, there are also cl ass variables, which apply to thedass itself and 
to all its instances. U nlike instance variables, whose values are stored in the instance, class 
variables’ values arestored in thedass itself. You’ll learn about class variables later on thisweek; 
you’ll learn more specifics about instance variables tomorrow. 

Behavior 

A class’s behavior determines what instances of that class do when their internal state changes 
or when that instance is asked to do something by another class or object. Behavior istheway 
objects can do anything to themselves or have anything doneto them. For example, to go back 
to thetheoretical Motorcycle class, herearesomebehaviorsthattheMotorcycie dassmight have: 

Z Start the engine 
Z Stop the engine 

□ Speed up 

Z Change gear 

□ Stall 

T o definean object’s behavior, you create methods, which look and behavejust likefunctions 
in other languages, but aredefined inside a class. Java does not have functionsdefined outside 
classes (as C++ does). 

NEW*' M eMs are functions defined inside classes that operate on instances of those classes. 

TERM 

M ethods don’t always affect only a single object; objects communicate with each other using 
methods as well. A class or object can call methods in another class or object to communicate 
changes in the environment or to ask that object to change its state. 

Just as there are instance and cl ass variables, there are also instance and class methods. Instance 
methods (which are so common they’re usually just called methods) apply and operate on an 
instance; dassmethodsapply and operateon aclass(oron other objects). You’ll learn moreabout 
class methods lata on this week. 

Creating a Class 

Uptothispoint, today’slesson has been prettytheoretical. I n thissection, you’ll createaworking 
example of the Motorcycle class so that you can see how instance variables and methods are 
defined in a class. You’ll also create a Java application that creates a new instance of the 
Motorcycle class and shows its instance variables. 
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Note: I’m not going to go into a lot of detail about the actual syntax of this 
example here. D on’t worry too much about it if you’re not really sure what’s going 
on; it will become clear to you later on this week. All you really need to worry 
about in this example is understanding the basic parts of this class definition. 



Ready? Let's start with a basic class definition. Open up that editor and enter the following: 

class Motorcycle { 



C ongratulations! You’venow created adass. 0 f course, it doesn't do very much at the moment, 
but that’s ajava class at its very simplest. 

First, let'screatesomeinstancevariablesforthisdass- three of them, to be specific. J ust below 
the first line, add thefollowing three lines: 

String make; 

String color; 
boolean engineState; 

H ere, you’ve created three instance variables: two, make and color, can contain string objects 
(string is part of that standard class library mentioned earlier). The third, enginestate, is a 
boolean that refers to whether the engine is off or on. 



Technical Note: boolean in Java is a real data type that can have the value true or 
false . U nlike C , booleans are not numbers. You’ll hear about this again tomorrow 
so you won’t forget. 



Now let'sadd some behavior (methods) to thedass. There are all kindsofthingsa motorcycle 
can do, but to keep things short, let'sadd just one method— a method that starts the engine. 
Add thefollowing lines bdow the instance variables in your class definition: 

void startEngine() { 

if (enginestate == true) 

System. out. println( "The engine is already on."); 
else { 

enginestate = true; 

System. out. println("The engine is now on."); 

} 

} 
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The startEngine method tests to see whether the engine is already running (in the line 
enginestate == true) and, if it is, merely printsa message to that effect. If theengineisn’t already 
running, it changes the state of the engine to true and then printsa message. 

W ith your methods and variables in place, save the program to a file called M otorcyde.java 
(remember, you should always name your J ava files the same names as the class they define). 
H ere’s what your program should look like so far: 

class Motorcycle { 

String make; 

String color; 
boolean enginestate; 

void startEngine () { 

if (enginestate == true) 

System. out. println("The engine is already on."); 
else { 

enginestate = true; 

System. out. println("The engine is now on."); 



X Tip: T he indentation of each part of the class isn’t important to thej ava compiler. 
Using some form of indentation, however, makes your class definition easier for 
you and for other people to read. The indentation used here, with instance vari- 
ables and methods indented from the class definition, is the style used throughout 
this book. Thej ava class libraries use a similar indentation. You can choose any 
indentation style that you like. 

Before you compile this class, let’s add one more method. TheshowAtts method prints the 
current values of the instance variables in an instance of your Motorcycle class. H ere’s what it 
looks like: 

void showAtts() { 

System. out. println( "This motorcycle is a " 

+ color + " " + make); 
if (enginestate == true) 

System. out. println("The engine is on."); 
else System, out. println( "The engine is off.' 1 ); 

> 

T heshowAtts method printstwo lines to thescreen: themake and color of themotorcydeobject, 
and whether or not the engine is on or off. 
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Save that file again and compile it using javac: 



javac Motorcycle . java 



Note: After this point, I’m going to assume you know how to compile and run Java 
programs. I won’t repeat this information after this. 



What happens if you now use thejava interpreter to run thiscompiled class?T ry it. Java assumes 
that this class is an application and looksforamain method. T his is just a class, however, so it 
doesn’t haveamain method. Thejava interpreter (java) gives you an error like this one: 



In class Motorcycle: void main(String argv[]) is not defined 



T o do something with the M otorcyde class— for example, to create instances of that class and 
play with them- you’re going to need to createajava application that usesthisdassoradd a 
main method to this one. For simplicity’s sake, let’s do the latter. Listing 2.1 shows the main o 
method you’ll add to the Motorcycle class (you’ll go over what this does in a bit). 



Type 



Listing 2.1. The main() method for Motorcycle, java. 



1: public static void main (String args [ ] ) { 

2 : Motorcycle m = new Motorcycle () ; 

3 : m.make = “Yamaha RZ350"; 

4 : m. color = “yellow"; 

5 : System. out. println( "Calling showAtts. . 

6: m. showAtts () ; 

7: System.out.println(" "); 

8: System. out. println( "Starting engine..."); 

9: m.startEngine() ; 

10 : System. out. println(" "); 

11 : System. out. println ("Calling showAtts..."); 

12 : m.showAtts() ; 

13 : System, out. println(" "); 

14 : System. out. println ("Starting engine..."); 

15 : m.startEngine() ; 

16 :} 



With the main o method, the Motorcycle class is now an application, and you can compile it 
again and this time it’ll run. H ere’show the output should look: 



Calling showAtts... 

This motorcycle is a yellow Yamaha RZ350 
The engine is off. 
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Starting engine. . . 

The engine is now on. 



Calling showAtts... 

This motorcycle is a yellow Yamaha RZ350 
The engine is on. 



Starting engine. . . 

The engine is already on. 

Analwdc Thecontmtsofthemain <) method areallgoingto look very new to you, so let'sgo through 
AlldiySIS it line by line so that you at least have a basic idea of what it does (you’ll get details about 
the specifics of all of this tomorrow and the day after). 

T hefirst linedeclaresthemarn < > method. T hemain ( > method alwayslookslikethis; you'll learn 
the specifics of each part later this week. 

Line 2, Motorcycle m = new Motorcycieo, creates a new instanceof theMotorcycie class and 
stores a reference to it in thevariablem. Remember, you don’t usually operate directly on classes 
in yourj ava programs; instead, you create objects from those classes and then modify and call 
methods in those objects. 

Lines3and4settheinstancevariablesforthismotorcydeobject:themakeisnow aYamaha RZ 350 
(a very pretty motorcycle from the mid-1980s), and the color is yeiiow. 

Lines 5 and 6 call theshowAttso method, defined in your motorcycle object. (Actually, only 
6 does; 5 just printsamessagethat you’reaboutto call this method. ) Thenew motorcycle object 
then printsout thevaluesof i ts i n stan ce vari ab I es — themake and color asyou set in the previous 
lines- and shows that the engine is off. 

Line 7 prints a divider line to the screen; this is just for prettier output. 

Line9callsthestartEngine() method in the motorcycle object to start the engine. The engine 
should now be on. 

Line 12 prints the values of the instance variables again. This time, the report should say the 
engine is now on. 

Line 15 triesto start theengineagain, just for fun. Because the engine isalready on, this should 
print the error message. 

Inheritance, Interfaces, and Packages 

N ow that you have a basic grasp of classes, objects, methods, variables, and how to put it all 
together in aj ava program, it’stimeto confuseyou again. I nheritance, interfaces, and packages 
areall mechanismsfororganizingdassesand class behaviors. Thejavadasslibrariesuse all these 
concepts, and thebest dasslibrariesyou writeforyour own programswill also usetheseconcepts. 
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Inheritance 

I nheritanceisoneofthemost crucial conceptsin object-oriented programming, and it hasavery 
direct effect on how you design and writeyourjava classes. I nheritanceisapowerful mechanism 
that meanswhen you writea dassyou only have to specify how that class is different from some 
other class, while also giving you dynamic access to the information contained in those other 
classes. 

NEW** W ith inheritance, all classes- thoseyou write, thosefrom other classlibrariesthatyou use, 
TERM and thosefrom the standard utility classes as well— are arranged in a strict hierarchy (see 
Figure 2.2). 

Each class has a superclass (the class above it in the hierarchy), and each class can have one or 
more subdasses(dasses below that cl ass in the hierarchy). Cl asses further down inthehierarchy 
are said to inherit from classes further up in the hierarchy. 



Figure 2.2. 

A class hierarchy. 




Subclassesinheritall themethodsand variablesfrom theirsuperclasses — that is, in any particular 
class, if thesuperdassdefinesbehaviorthatyourdassneeds, you don’t haveto redefineitorcopy 
that codefrom some other class. Your class automatically gets that behavior from its superclass, 
that superclass gets behavior from its superclass, and so on all the way up the hierarchy. Your 
class becomes a combination of all the features of the classes above it in the hierarchy. 

AtthetopoftheJavaclasshierarchyisthedassobject;alldassesinheritfromthisonesuperdass. 
object isthemost general class in the hierarchy; it defines behavior specific to all objectsin the 
Java class hierarchy. Each class farther down in the hierarchy adds more information and 
becomes more tailored to a specific purpose. In this way, you can think of a class hierarchy as 
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defining very abstract concepts at the top of the hierarchy and those ideas becoming more 
concrete the farther down the chain of superclasses you go. 

M ost of the time when you write new Java classes, you’ll want to create a class that has all the 
information some other class has, plus some extra information. For example, you may want a 
version of aButton with itsown built-in label. To get all the Button information, all you have 
to do isdefineyourdassto inherit from Button. Your dasswill automatically get all thebehavior 
defined in Button (and in Button’s superclasses), so all you have to worry about are the things 
that makeyour dassdifferent from Button itself. T hismechanism for defining new classes asthe 
differences between them and their superclasses is cal led subclassing. 

NEW#- Subclassing involves creating a new class that inherits from some other class in the class 
TERM hierarchy. U sing subclassing, you only need to define the differences between your class 
and its parent; the additional behavior is all available to your class through inheritance. 

W hat if your cl assdefines entirely new behavior, and isn't really asubdassof another class?Your 
class can also inherit directly from object, which still allows it to fit neatly into thej ava class 
hierarchy. In fact, if you create a class definition that doesn’t indicate its superclass in thefirst 
line, Java automaticallyassumesyou’reinheritingfrom object. TheMotorcyciedassyou created 
in the previous section inherited from object. 

C reating a C lass H ierarchy 

I f you're creating a larger set of classes, it makes sense for your classes not only to inherit from 
the existing class hierarchy, but also to make up a hierarchy themselves. This may take some 
planning beforehand when you're trying to figureout how to organize your J ava code, but the 
advantages are significant once it’s done: 

Z W hen you devdop your classes in a hierarchy, you can factor out information com- 
mon to multiple classes in superclasses, and then reuse that superclass’s information 
over and over again. Each subclass gets that common information from its superclass. 

Z C hanging (or inserting) a class further up in the hierarchy automatically changes the 
behavior of the lower classes— no need to change or recompile any of the lower 
classes, because they get the new information through inheritance and not by copying 
any of the code. 

For example, let’sgo back to that Motorcycle class, and pretend you created aj ava program to 
implement all thefeaturesof a motorcycle. I t’sdone, it works, and everything isfine. N ow, your 
next task isto create aj ava class called car. 

car and Motorcycle have many similar features- both are vehicles driven by engines. Both 
havetransmissionsand headlampsand speedometers. So, yourfirst impulse may beto open up 
your Motorcycle class file and copy over a lot of the information you already defined into the 
new class car. 



A far better plan is to factor out the common information for car and Motorcycle into a more 
gen eraldasshierarchy.ThismaybealotofworkjustfortheclassesMotorcycieandcar, but once 
you add Bicycle, scooter, Truck, and so on, having common behavior in a reuseable superclass 
significantly reduces the amount of work you have to do overall. 

Let'sdesign a cl ass hierarchy that might serve thispurpose. Starting at thetopisthedassobject, 
which is the root of all Java classes. The most general class to which motorcycle and car both 
belong might be called vehicle. A vehicle, generally, isdefined asathingthat propels someone 
from one place to another. In the vehicle class, you define only the behavior that enables 
someone to be propelled from point a to point b, and nothing more. 

BelOW Vehicle? H OW about tWO Classes: PersonPoweredVehicle and EnginePoweredVehicle? 

EnginePoweredvehicie is different from vehicle because is has an engine, and the behaviors 
might includestopping and starting theengine, having certain amountsofgasolineand oil, and 
perhaps the speed or gear in which the engine is running. Person-powered vehicles have some 
kind of mechanism for translating people motion into vehicle motion— pedals, for example. 
Figure 2.3 shows what you have so far. 



Figure 2.3. 

The basic vehicle hierarchy. 




Now, let’s become even more specific. With EnginePoweredvehicie, you might have several 
classes: Motorcycle, car, Truck, and so on. 0 r you can factor out still more behavior and have 
intermediateclassesforTwowheeied and Fourwheeied vehicles, with different behaviors for each 
(see Figure 2.4). 

Finally, with asubdassforthetwo-wheeled engine-powered vehidesyou can finally haveadass 
for motorcycles. Alternatively, you could additionally define scooters and mopeds, both of 
which are two-wheeled engine-powered vehicles but havedifferent qualitiesfrom motorcycles. 

Where do qualities such as make or color come in? Wherever you want them to go— or, more 
usually, where they fit most naturally in the class hierarchy. You can definethemakeand color 
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on vehicle, and all thesubdasseswill have those vari ables aswell. T he point to remember isthat 
you have to define a feature or a behavior only once in the hierarchy; it’s automatically reused 
by each subclass. 



Figure 2.4. 

Two-wheeled and four- 
wheeled vehicles 




H ow I nheritance Works 

H owdoesinheritancework?H owisit that instancesofonedass can automatically get variables 
and methods from the classes further up in the hierarchy? 

For instance variables, when you createanewinstanceofadass,you geta"slot" for each vari able 
defined in the current class and for each variable defined in all its superclasses. In this way, all 
the classes combine to form a template for the current object and then each object fillsin the 
information appropriate to its situation. 

M ethods operate similarly: new objects have access to all the method names of its class and its 
superclasses, but method definitions are chosen dynamically when a method iscalled. That is, 
if you call amethod on a particular object, Java first checks the object'sclassfor thedefinition 
of that method. If it’s not defined in the object’s class, it looksin that class's superclass, and so 
on up the chain until the method definition isfound (see Figure 2.5). 

T hingsget complicated when asubdassdefinesamethod that hasthesamesignature(nameand 
number and type of arguments) as a method defined in a superclass. I n this case, the method 
definition that isfound first (starting at the bottom and working upward toward the top of the 
hierarchy) is the one that is actually executed. Because of this, you can purposefully define a 
method in asubdassthat has thesamesignatureasa method in a superclass, which then "hides" 
the superclass’s method. This is called overriding a method. You’ll learn all about methods on 
Day 7. 
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Figure 2.5. 

H ow methods are located. 



Method 

definition 




NEW«~ Overriding a method iscreating a method in asubdassthathasthesamesignature(name, 
TERM number and typeof arguments) asa method in asuperdass. T hat new method then hides 
the superclass’s method (see Figure 2.6). 



Figure 2.6. 

Overriding methods 





Object-Oriented Programming and J ava 



Single and Multiple I nheritance 

Java’sform of inheritance, as you learned in the previous sections, is called single inheritance. 
Singleinheritance means that each J ava class can have only one superclass (although any given 
superclass can have multiple subclasses). 

In other object-oriented programming languages, such asC-H-and Smalltalk, classes can have 
more than one superclass, and they inherit combined variables and methods from all those 
classes. This is called multiple inheritance. M ultiple inheritance can provide enormous power 
in terms of being able to create cl asses that factor just about all imaginable behavior, but it can 
also significantly complicate class definitions and the code to produce them. Java makes 
inheritance simpler by being only singly inherited. 

Interfaces and Packages 

Java has two remaining concepts to discuss here: packages and interfaces. Both are advanced 
topicsfor implementing and designing groups of classes and class behavior. You’ll learn about 
both interfaces and packages on D ay 16, but they are worth at least introducing here. 

Recall thatj avadasseshaveonlyasinglesuperdass, and they inherit variablesand methodsfrom 
that superclass and all its superclasses. Although single inheritance makes the relationship 
between classes and thefunctionality thosedassesimplement easy to understand and to design, 
it can also be somewhat restricting— in particular, when you have similar behavior that needs 
to be duplicated across different "branches” of the class hierarchy. Java solves this problem of 
shared behavior by using the concept of interfaces. 

NEW*' An i nterfaceisacollection of method names, without actual definitions, that indicatethat 
TERM adasshasasetofbehaviorsin addition to thebehaviorsthedassgetsfromitssuperdasses. 

Although a si nglej ava class can have only onesuperclass(dueto single inheritance), that class 
can also implement any number of interfaces. By implementing an interface, a class provides 
method implementations (definitions) for the method names defined by the interface. If two 
verydisparatedassesimplementthesame interface, they can both respond to thesame method 
calls (as defined by that interface), although what each class actually does in response to those 
method calls may be very different. 

You don’t need to know very much about interfaces right now. You'll learn more as the book 
progresses, so if all this is very confusing, don't panic! 

T he final new J ava concept for today is that of packages. 

NEW*' Packages in J ava are a way of grouping together related classes and interfaces. Packages 
TERM enable modular groups of classes to be available only if they are needed and diminate 
potential conflicts between class names in different groups of classes. 



You’ll learn all about packages, including how to createand usethem, in W eek 3. For now, there 
are only a few things you need to know: 

□ The class libraries in thejava Developer’s Kit are contained in a package called java. 
Thedassesin the java package are guaranteed to be available in any Java implementa- 
tion, and are the only classes guaranteed to be available across different implementa- 
tions. The java package itself contains other packages for classes that define the 
language itself, the input and output classes, some basic networking, and the window 
toolkit functions. C lasses in other packages (for example, classes in the sun or netscape 
packages) may be available only in specific implementations. 

'O By default, your J ava classes have access to only the classes in java.lang (the base 
language package inside the java package). T o use classes from any other package, you 
have to either refer to them explicitly by package name or import them in your source 
file. 

IP To refer to a class within a package, list all the packages that class is contained in and 
the class name, all separated by periods (.). For example, take the color class, which is 
contained in the awt package (awt stands for Abstract W indowing T oolkit). T he awt 
package, in turn, is inside the java package. T o refer to the color class in your pro- 
gram, you use the notation java. awt. color. 

Creating a Subclass 

T o finish up today, let’s create a class that is a subclass of another class and override some 
methods. You’ll also get a basic feel for how packages work in thisexample. 

Probably the most typical instance of creating a subclass, at least when you first start 
programming in J ava, isincreatingan applet. All appletsaresubdassesofthedassAppiet (which 
i s part of the j ava . applet package) . By creati ng a subclass of Applet, you automati cal ly get al I 
thebeh aviorfromthewindow toolkit and thelayoutdassesthatenablesyour applet to bedrawn 
in the right place on the page and to interact with system operations, such as keypresses and 
mouse clicks 

In thisexample, you’ll create an applet similar to the FI ello World applet from yesterday, but 
one that drawsthe Heiio string in a larger font and a different color. T o start thisexample, let’s 
first construct the class definition itself. Remember the FI T M L and classes directories you 
created yesterday? Let’s go back to those, go back to your text editor, and enterthefollowing class 
definition: 

public class HelloAgainApplet extends java. applet. Applet { 

> 

FI ere, you’re creating a class called HeiioAgainAppiet. Note the part that says extends 
java, applet. Applet- that’sthe part that says your applet dassisasubdassoftheAppiet class. 
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Note that because the Applet class is contained in the java, applet package, you don’t have 
automatic accessto that class, and you have to refer to it explicitly by package and class name. 

The other part of this class definition is the public keyword. Public means that your class is 
available to thej ava system at large once it is loaded. M ost of the time you need to make a class 
public only if you want it to bevisibleto all the other cl asses in your J ava program; but applets, 
in particular, must bedeclared to be public. (You’ll learn more about public dassesin W eek 3.) 

A class definition with nothing in it doesn't really have much of a point; without adding or 
overriding any of its superclasses' variables or methods, there's no point to creating a subclass 
at all. Let’s add some information to this class to make it different from its superclass. 

First, add an instance variable to contain a Font object: 

Font f = new Font("TimesRoman" , Font. BOLD, 36) ; 

The f instance variable now contains a new instance of the class Font, part of the java.awt 
package. T his particular font object is a T imes Roman font, boldface, 36 points high. I n the 
previous H ello World applet, the font used for the text was the default font: 12 point Times 
Roman. Using a font object, you can change the font of the text you draw in your applet. 

By creating an instance variableto hold thisfont object, you makeit availableto all themethods 
in your class. N ow let's create a method that uses it. 

W hen you writeapplets, there are several "standard” methodsdefined in theapplet superclasses 
that you will commonly override in your applet class. These include methods to initialize the 
applet, to start it running, to handle operations such as mouse movements or mouse clicks, or 
to clean up when the applet stops running. One of those standard methods is the paint o 
method, which actually displaysyour applet on screen. Thedefault definition of paint o doesn’t 
do anything— it’san empty method. By overriding paint o, you tell theapplet just what to draw 
on the screen. H ere’s a definition of pamto: 

public void paint (Graphics g) { 
g.setFont(f) ; 
g.setColor(Color.red) ; 
g. drawstring ( "Hello again!", 5, 25); 

> 

T herearetwo thingsto know about thepaint ( > method. First, notethatthismethod isdeclared 
public, just as the applet itself was. The pamto method is actually public for a different 
reason- becausethe method it’soverridingisal so public. If you try to overridea method in your 
own class that’s public in a superclass, you get a compiler error, so the public is required. 

Secondly, note that the pamto method takes a single argument: an instance of the Graphics 
class. The Graphics class provides platform-independent behavior for rendering fonts, colors, 
and basic drawing operations. You’ll learn a lot more about theGraphics dassin W eek 2, when 
you create more extensive applets. 
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I nside your painto method, you’ve done three things: 

□ You’ve told the graphics object that the default drawing font will be the one contained 
in the instance variable t. 

□ You’ve told the graphics object that the default color is an instance of the color class 
for the color red. 

□ finally, you’ve drawn your "Heiio Again! " string onto the screen itself, at the x and y 
positions of 5 and 25. The string will be rendered in the default font and color. 

For an applet this simple, this is all you need to do. H ere's what the applet looks like so far: 

public class HelloAgainApplet extends java. applet. Applet { 

Font f = new Font ( "TimesRoman" , Font .BOLD, 36) ; 

public void paint (Graphics g) { 
g.setFont(f ) ; 
g.setColor(Color.red) ; 
g.drawString("Hello again!", 5, 50); 



If you’ve been paying attention, you’ll notice something is wrong with this example up to this 
point. If you don’t know what it is, try saving this file (remember, save it to the same name as 
the class: H elloAgainApplet.java) and compiling it using thejava compiler. You should get a 
bunch of errors similar to this one: 

HelloAgainApplet. java : 7 : Class Graphics not found in type declaration. 

W hy are you getting these errors? Because the classes you’re referring to are part of a package. 
Remember that theonlypackageyou haveaccessto automatically is java.iang. You referred to 
the Applet class in the first line of the class definition by referring to its full package name 
(java, applet. Applet). Further on in the program, however, you referred to all kinds of other 
classes as if they were already available. 

There are two ways to solve this problem: refer to all external classes by full package name or 
importtheappropriatedassorpackageatthebeginningofyourdassfileWhichoneyou choose 
to do is mostly a matter of choice, although if you find yoursdf referring to a cl ass in another 
package lots of times, you may want to import it to cut down on the amount of typing. 

I n thisexample, you’ll import thedassesyou need. T herearethreeof them: Graphics, Font, and 
color. All three are part of thejava.awt package. FI ere are thelinesto import thesedasses. These 
lines go at the top of your program, before the actual class definition: 

import java.awt. Graphics; 
import java.awt. Font; 
import java.awt. Color; 
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Tip: You also can import an entire package of (public) classes by using an asterisk 
(*) in place of a specific class name. For example, to import all thedassesin theawt 
package, you can use this line: 



N ow, with the proper classes imported into your program, H dloAgainApplet should compile 
cleanly to a class file. T o test it, createan HTML filewith the<APPLET> tag as you did yesterday. 
H ere'san HTML file to use: 

<HTML> 

<HEAD> 

<TITLE>Another Applet</TITLE> 

</HEAD> 

<BODY> 

<P>My second Java applet says: 

<APPLET CODE= " HelloAgainApplet . Class " WIDTH=200 HEIGHT=50> 

</APPLET> 

</BODY> 

</HTML> 

ForthisHTM L example, yourjava class fileisin the same directory asthisH TM L file. Save 
thefiletoH dloAgainApplet. html and fireupyourjava-awarebrowserorthej ava applet viewer. 
Figure 2.7 shows the result you should begetting (the H dlo Again string is red). 



Figure 2.7. 

T he H ello Again applet. 



My Mtnnd I *v» «wJet nyr 

Hello Again! 



Summary 

I fthisisyour first encounter with object-oriented programming, a lot of the information in this 
chapter isgoingto seem really theoretical and overwhelming. Fear not— thefurther along in this 
book you get, and the morej ava applications you create, the easier it is to understand. 

0 ne of the biggest hurdles of object-oriented programming is not necessarily the concepts, it’s 
thdr names. 0 0 P has lots of jargon surrounding it. T o summarize today’s material, here’s a 
glossary of terms and concepts you learned today: 
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C lass A template for an object, which contains variables and methods representing 
behavior and attributes. Classes can inherit variables and methods from other classes. 
Object: A concrete instance of some class. M ultiple objects that are instances of the 
same class have access to the same methods, but often have different values for their 
instance variables. 

Instance: The same thing as an object; each object isan instance of some class. 
Superclass A class further up in the inheritance hierarchy than its child, the subclass. 
Subclass A class lower in the inheritance hierarchy than its parent, the superclass. 
When you create a new class, that's often called subclassing. 

I nstance method: A method defined in a class, which operates on an instance of that 
class. I nstance methods are usually called just methods 
C lass method: A method defined in a class, which can operate on the class itself or on 
any object. 

Instance variable: A variablethat isowned by an individual instance and whose valueis 
stored in the instance. 

Class variable: A variablethat isowned by the class and all its instances as a whole, and 
is stored in the class. 

Interface: A collection of abstract behavior specifications that individual classes can 
then implement. 

Package: A collection of classes and interfaces. Classes from packages other than 
java.lang must be explicitly imported or referred to by full package name. 

Q&A 

Q Methods are effectively functions that are defined inside classes. If they look like 
functions and act like functions, why aren't they called functions? 

A Some object-oriented programming languages do call them functions (C++ calls them 
member functions). Other object-oriented languages differentiate between functions 
inside and outside a body of a class or object, where having separate terms is impor- 
tant to understanding how each works. Because the difference is relevant in other 
languages, and because the term method is now in such common use in object- 
oriented technology, Java uses the word as well. 

Q I understand instance variables and methods, but not class variables and 
methods. 

A M ost everything you do in ajava program will be with objects. Some behaviors and 
attributes, however, make more sense if they are stored in the class itself rather than in 
the object. For example, to create a new instance of a class, you need a method that is 
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defined for the class itself, not for an object. (0 therwise, how can you create an 
instance of dass?You need an object to call the new method in, but you don’t have an 
object yet.) Class variables, on the other hand, are often used when you have an 
attribute whose value you want to share with the instances of a class. 

Most of the time, you’ll use instance variables and methods. You’ll learn more about 
class variables and methods later on this week. 




Java Basics 



On Days 1 and 2, you learned about Java programming in very broad terms— what a Java 
program and an executablelook like, and how to createsimpledasses. For the remainder of this 
week, you’re going to get down to details and deal with the specifics of what thejava language 
looks like. 

T oday, you won’t define any classes or objects or worry about how any of them communicate 
insideajava program. Rather, you’ll draw closer and examinesimplejava statements- thebasic 
things you can do in Java within a method definition such as mam o* 

T oday you’ll learn about the following: 

□ J ava statements and expressions 

□ Variables and datatypes 
□t Comments 

fit literals 
Z Arithmetic 

□ Comparisons 

3 . logical operators 



Technical Note: Java looks a lot I ike C++, and— by extension— like C. M uch of 
the syntax will be very familiar to you if you are used to working in these languages. 
I f you are an experienced C or C ++ programmer, you may want to pay special 
attention to theT echnical Notes (such as this one), because they will provide 
information about the specific differences between these and other traditional 
languages and Java. 



Statements and Expressions 

A statement isthesimplest thing you can do in Java; a statement formsa singlejava operation. 
All the following are simple J ava statements: 



import j ava. awt. Font; 

System. out. println("This motorcycle is a " 

+ color + " " + make); 
m.engineState = true; 

Statements sometimes return values— for example, when you add two numberstogetherortest 
to see whether one value is equal to another. These kind of statements are called expressions. 
We’ll discuss these later on today. 
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T he most important thing to remember about J ava statements is that each one ends with a 
semicolon. Forget the semicolon and your Java program won’t compile. 

Java also has compound statements, or blocks, which can be placed whereverasinglestatement 
can. Block statements are surrounded by braces({>). You’ll learn more about blocksin Chapter 
5, "Arrays, Conditionals, and Loops.” 



Variables and Data Types 

Variables are locations in memoryin which values can be stored. They have a name, atype, and 
avalue. Before you can useavariable, you have to declare it. After it is declared, you can then 
assign values to it. 

J ava actually hasthree kindsof variables: instance variables, class variables, and local variables. 

Instance variables, as you learned yesterday, are used to define attributes or the state for a 
particular object. Class variables aresimilar to instance variables, except their values apply to all 
that class’s instances (and to the class itself) rather than having different values for each object. 

Local variables aredeclared and used insidemethod definitions, for example, for index counters 
in loops, as temporary variables, or to hold values that you need only inside the method 
definition itself. T hey can also beused insideblocks({}), which you’ll learn about laterthisweek. 
0 ncethemethod (or block) finishesexecuting, thevariabledefinition and itsvalueceaseto exist. 
U selocal variablesto store information needed by asinglemethod and instance variablesto store 
information needed by multiple methods in the object. 

Although all three kindsof variables are declared in much the same ways, class and instance 
variables are accessed and assigned in slightly different ways from local variables. Today, you’ll 
focuson variables as used within method definitions; tomorrow, you’ll learn how to deal with 
instance and class variables. 



N ote: U nlike other languages, J ava does not have global variables— that is, vari- 
ables that are global to all parts of a program. Instance and class variables can be 
used to communicate global information between and among objects. Remember, 
Java is an object-oriented language, so you should think in terms of objects and 
how they interact, rather than in terms of programs. 



D eclaring Variables 

To use any variable in aj ava program, you must first d eel are i t. V ari abl e d eel arati o n s con si st of 
a type and a variable name: 
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int myAge; 

String myName; 
boolean isTired; 

Variable definitions can go anywhere in a method definition (that is, anywhere a regular Java 
statement can go), although they aremost commonly declared at thebeginning of thedefinition 
before they are used: 

public static void main (String args4-]) { 
int count; 

String title; 
boolean isAsleep; 



You can string together variable names with the same type: 

int x, y, z; 

String firstName, LastName; 

You can also give each variable an initial value when you declare it: 

int myAge, mySize, numShoes = 28; 

String myName = "Laura"; 
boolean isTired = true; 
int a = 4, b = 5, c = 6; 

If there are multiple variables on the same line with only one initializer (as in the first of the 
previousexamples), theinitial valueappliesto only thelast variablein adeclaration. You can also 
group individual variables and initializers on the same line using commas, as with the last 
example, above. 

Local variablesmust begiven valuesbeforethey can beused (yourj avaprogram will not compile 
if you try to use an unassigned local variable). For this reason, it’sagood idea always to give local 
variables initial values. Instance and class variabledefinitionsdo not have this restriction (their 
initial value depends on the type of the variable: nun for instances of classes, 0 for numeric 
variables, ■ \o ■ for characters, and false for booleans). 

Notes on Variable Names 

Variablenam esinjava can start with a letter, an underscore (_), or adollar sign ($). They cannot 
start with a number. After the first character, your variable names can include any letter or 
number. Symbols, such as%, *, 0 , and so on, areoften reserved for operatorsin J ava, so be careful 
when using symbols in variable names. 

In addition, the Java language uses the U nicode character set. U nicode is a character set 
definition that not only offers characters in the standard ASC 1 1 character set, but also several 
million other charactersfor representing most international alphabets. This meansthat you can 
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use accented charactersand other glyphsaslegalcharactersinvariablenames,aslongasthey have 
a U nicode character number above 0000. 




Caution: T hell nicode specification is a two-volume set of lists of thousands of 
characters. If you don’t understand Unicode, or don’t think you have a use for it, 
it’s safest just to use plain numbers and letters in your variable names. You’ll learn a 
little more about U nicode later on. 



Finally, note that the Java language is case-sensitive, which means that uppercase letters are 
differentfrom lowercase letters. This means that the variable x is different from thevariablex, 
and a rose is not a Rose is not a rose. Keep this in mind as you write your own J ava programs 
and as you read J ava code other people have written. 

By convention, Java variables have meaningful names, often made up of several words 
combined. The first word islowercase, but all following words have an initial uppercase letter: 

Button theButton; 
long reallyBigNumber; 

boolean currentWeatherStateOf PlanetXShortVersion ; 

Variable Types 

I n addition to the variable name, each vari abl e d eel arati on must haveatype, which defineswhat 
values that variable can hold. The variable type can be one of three things: 

□1 fine of the eight basic primitive data types 
□ The name of a class 
□I An array 

You’ll learn about how to declare and use array variables in Chapter 5 . 

The eight primitive data types handle common types for integers, floating-point numbers, 
characters, and boolean valuesftrueor false). T hey'recalled primitive because they're built into 
the system and are not actual objects, which makes them more efficient to use. N ote that these 
data types are machine-independent, which means that you can rely on their sizes and 
characteristics to be consistent across your Java programs. 

T here arefourj ava integer types, each with different ranges of values (as listed in T able 3 . 1 ). All 
are signed, which means they can hold either positive or negative numbers. W hich type you 
choose for your variables depends on the range of values you expect that variable to hold; if a 
value becomes too big for the variable type, it istruncated. 




Table 3.1. Integer types. 



Type 


Size 


Range 


byte 


8 bits 


-128 to 127 


short 


16 bits 


-32,768 to 32,767 


int 


32 bits 


-2,147,483,648 to 2,147,483,647 


long 


64 bits 


-9223372036854775808 to 9223372036854775807 



Floating-point numbersareused for numberswith a decimal part. Java floating-point numbers 
are compliant with IEEE 754 (an international standard for defining floating-point numbers 
and arithmetic). T herearetwo floating-point types: float (32 bits, single-precision) and double 
(64 bits, double-precision). 

T hechar type isused for individual characters. BecauseJ ava usesthell ni code character set, the 
char type has 16 bits of precision, unsigned. 

Finally, the boolean type can have one of two values, true or false. N ote that unlike in other 
C -like languages, boolean is not a number, nor can it be treated as one. All tests of boolean 
variables should test for true or false. 

I n addition to theeight basic datatypes, variablesin J ava can also bedeclared to hold an instance 
of a particular class: 

String LastName; 

Font basicFont; 

OvalShape myOval; 

Each of these variables can then hold only instancesof thegiven class. Asyou createnew classes, 
you can declare variables to hold instancesof those classes (and their subclasses) as well. 



T echnical N ote: J ava does not have a typedef statement (as in C and C ++). T o 
declare new types in J ava, you declare a new class; then variables can be declared to 
be of that class’s type. 



Assigning Values to Variables 

O nceavariablehasbeen declared, you can assign a valueto that variableby using theassignment 
operator =: 



size = 14; 

tooMuchCaff iene = true; 



Comments 

J ava has three kindsof comments. /* and */ surround multilinecomments, asin C or C ++. All 
text between the two delimiters is ignored: 

/* I don't know how I wrote this next part; I was working 
really late one night and it just sort of appeared. I 
suspect the code elves did it for me. It might be wise 
not to try and change it. 

*/ 

C omments cannot be nested; that is, you cannot have a comment inside a comment. 

Double-slashes (//) can be used for a single line of comment. All the text up to the end of the 
line is ignored: 

int vices = 7; // are there really only 7 vices? 

Thefinal type of comment begins with /**and ends with */. These are special comments that 
are used forthejavadoc system. Javadoc is used to generateAPI documentation from the code. 
You won’t learn about javadoc in this book; you can find out more information from the 
documentation that camewith Sun’sJavaDeveloper’sKitorfromSun’sJavahomepagefhttp:/ 

/java. sun. com). 

Literals 

Literals are used to indicate simplevalues in your Java programs. 

NEW** Literal is a programming language term, which essentially means that what you type is 
TERM whatyou get. Forexample, if you type4 in aj avaprogram, you automaticallyget an integer 
with the value 4. If you type ‘a 1 , you get a character with the value a. 

Literals may seem intuitive most of thetime, but there are some special cases of literals in Java 
for different kindsof numbers, characters, strings, and boolean values. 

Number Literals 

There are several integer literals. 4, forexample, isadecimal integer literal oftypemt (although 
you can assign it to a variable of type byte or short because it’s small enough to fit into those 
types). A decimal integer literal larger than an mt ^automatically of typeiong. You also can force 
a smaller number to a long by appending an l or 1 to that number (for example, 4L is a long 
integer of value 4). Negative integers are preceded by a minus sign— forexample, -45. 

Integers can also be expressed as octal or hexadecimal: a leading 0 indicates that a number is 
octal— for example, 0777 or 0004. A leading 0x (or 0x) means that it is in hex (0xff, 0XAF45). 




H exadecimal numbers can contain regular digits(0-9) orupper- or lowercasehexdigits(a-f or 
A-F). 

Floating-point literals usually have two parts: the integer part and the decimal part— for 
example, 5.677777. Floating-point literals result in a floating-point number of type double, 
regardless of the precision of that number. You can force the number to the type float by 
appending the letter t (or f) to that number— for example, 2.56F. 

You can use exponents in floating-point literals using the letter e or e followed by the exponent 
(which can be a negative number): iee45 or .36E-2. 

Boolean Literals 

Boolean literalsconsistofthekeywordstrueand false. These keywords can beused anywhere 
you need a test or as the only possible values for boolean variables. 

Character Literals 

C haracter I iteral s are expressed byasinglecharactersurrounded by single quotes: 'a 1 , ■#■, -3 ■ , 



and so on. Characters are stored as 16-bit U ni code characters. T able 3.2 lists the special codes 
that can represent nonprintablecharacters, aswell as characters from thell ni code character set. 
T he letter d in the octal, hex, and Unicode escapes represents a number or a hexadecimal digit 
(a-f or A-F). 

Table 3.2. Character escape codes. 


Escape 


Meaning 


\n 


Newline 


\t 


Tab 


\b 


Backspace 


\r 


Carriage return 


\f 


Formfeed 


\\ 


Backslash 


V 


Single quote 


\" 


Double quote 


\ddd 


Octal 


\xdd 


FI exadecimal 


\udddd 


Unicode character 



Technical Note:C and C++ programmers should note that Java does not include 
character codes for \a (bell) or w (vertical tab). 



String Literals 

A combination of characters is a string. Strings in J ava are instances of the classString. Strings 
are not simplearrays of characters as they arein C orC++, although they do have many array- 
like characteristics (for example, you can test their length and add and delete individual 
characters as if they were arrays). Because string objects are real objects in Java, they have 
methodsthat enableyou to combine, test, and modify strings very easily. 

String literals consist of a series of characters inside double quotes: 

"Hi, I'm a string literal." 

"" //an empty string 

Strings can contain character constants such as newline, tab, and U nicode characters: 

"A string with a \t tab in it" 

"Nested strings are \ "strings inside of\" other strings" 

"This string brought to you by Java\u2122" 

I n thelast example, the U nicodecodesequencefor \u2122 producesa trademark symbol (™ ). 
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Note: Just because you can represent a character using a U nicode escape does not 
mean your computer can display that character— the computer or operating system 
you are running may not support U nicode, or the font you’re using may not have a 
glyph (picture) for that character. All that Unicode escapes in Java provide is a way 
to encode special characters for systems that support U nicode. 



When you use a string literal inyourjava program, Java automatically createsan instanceofthe 
classstring foryou with thevalueyou giveit. Stringsareunusual in thisrespect; theother literals 
do not behave in this way (none of the primitive base types are actual objects), and usually 
creating anew object involvesexplicitlycreatinganewinstanceofadass. You’ll learn moreabout 
strings, the String class, and the things you can do with strings later today and tomorrow. 
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Expressions and Operators 

Expressions are the simplest form of statement in J ava that actually accomplishes something. 
NEW«~ Expreaonsarestatementsthat return a value. 

TERM operators are special symbolsthat are commonly used in expressions. 

Arithmetic and tests for equality and magnitudearecommon examplesof expressions. Because 
they return a value, you can assign that result to a variable or test that value in other Java 
statements. 

0 perators in Java include arithmetic, various forms of assignment, increment and decrement, 
and logical operations. This section describes all these things. 



Arithmetic 



Java has five operators for basic arithmetic (seeT able 3.3). 

Table 3.3. Arithmetic operators. 


0 perator 


Meaning 


Example 


+ 


Addition 


3 + 4 




Subtraction 


5-7 




M ulti plication 


5*5 




Division 


14 r 7 


% 


M odulus 


20 % 7 



Each operator takes two operands, oneon either sideof the operator. The subtraction operator 
(-) can also be used to negate a single operand. 

Integer division results in an integer. Because integers don't have decimal fractions, any 
remainder is ignored. The expression 31 -r- 9 , for example, results in 3 (9 goes into 31 only 3 
times). 

M odulus(%) gives theremainder once the operands have been evenly divided. For example, 31 
% 9 results in 4 because 9 goes into 31 three times, with 4 leftover. 

N otethat, for integers, the result type of most operations is an mt or a long, regardless of the 
original typeoftheoperands. Largeresultsareoftypeiong; all othersareint.Arithmeticwherein 
one operand is an integer and another is a floating point results in a floating-point result. (If 
you’re interested in thedetailsof howj ava promotes and converts numeric typesfromonetype 
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to another, you may want to check out thejava Language Specification; that’s more detail than 
I want to cover here.) 



Listing 3.1 is an example of simple arithmetic. 




x is 6, y is 4 
x + y = 10 
x - y = 2 
x / y = 1 
x % y = 2 
a is 12.5, b is 7 
a / b = 1 .78571 

| ■ I n thissimplej avaapplication (notethemain ( > method), you initially definefour variables 
lySS in Iines3 through 6: x and y, which are integers (type int), and a and b, which arefloating- 
point numbers (type float). Keep in mind that thedefault type for floating-point literals 
(such as 12.5) isdoubie, so to make sure these are numbers of type float, you have to use an t 
after each one (lines 5 and 6). 



Theremainderoftheprogram merely doessome math with integers and floating point numbers 
and prints out the results. 

T here is one other thing to mention about this program: the method system . out . printm ( ) . 
You’ve seen this method on previous days, but you haven’t really learned exactly what it does. 
The system. out. printing ) method merely prints a message to the standard output of your 
system- to thescreen, to aspecial window, or maybejusttoaspecial log file, dependingon your 
system and the development environment you’re running (Sun’sJ D K prints it to thescreen). 
The system. out. printino method takes a single argument- a string- but you can use + to 
concatenate values into a string, as you’ll learn later today. 






^ Java Basics 



More About Assignment 

Variable assignment is a form of expression; in fact, because one assignment expression results 
in a value, you can string them together like this: 

x = y = z = 0; 

In this example, all three variables now have the value 0. 

Therightsideof an assignment expression isalwaysevaluated beforetheassignmenttakesplace. 
T his means that expressions such as x = x + 2 do the right thing; 2 is added to the value of x, 
and then that new value is reassigned to x. In fact, this sort of operation isso common that Java 
has several operators to do a shorthand version of this, borrowed from C and C++. T able 3.4 
shows these shorthand assignment operators. 

Table 3.4. Assignment operators. 



Expression 


Meaning 


x += y 


x =x +y 


x -= y 


x +x- y 


x *= y 


x=x*y 


x += y 


x=x-^y 
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6: 

7: 

8: 

9: 

10: 

11 : 

12 : 

13: 

14: 

15: 

16: 

17: 

18: 

19: 

20: 

21 : 

22: 

23: 

24: 

25: 

26: 

27: > 

28: 

29: } 



for example, the following two expressions: 



5 two expressions give very different results because of the difference between prefix and 
x. W hen you use postfix operators (x++ or x— ), y gets the value of x before before x is 
mented; using prefix, thevalueofx isassigned to y after theincrement hasoccurred. Listing 
;ajava example of how all this works. 

Listing 3.2. Test of prefix and postfix increment operators. 

lass PrePostFixTest { 

'Ublic static void main (String args[]) { 
int x = 0; 
int y = 0; 

System.out.println("x and y are " + x + “ and " + y ); 

System. out. println("x++ results in " + x); 

System. out. println("++x results in " + x); 

System. out. printing “Resetting x back to 0.“); 
x = 0; 

System . out . println ( 11 " ) ; 

y = x++; 

System.out.println("y = x++ (postfix) results in:' 1 ); 

System. out. println("x is " + x); 

System. out. println ("y is " + y); 

System . out . println ( 11 " ) ; 

y = ++x; 

System. out. println("y = ++x (prefix) results in:"); 

System. out. println("x is " + x); 

System. out. println ("y is " + y); 

System . out . println ( " " ) ; 



and y are 0 and 0 
h+ results in 1 
hx results in 2 





Resetting x back to 0. 



y = x++ (postfix) results in: 



y is 0 



y = ++x 
x is 2 
y is 2 



(prefix) results in: 
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lAn<dvdd 1 n the first part of this ^^P 16 ' y° u increment x alone using both prefix and postfix 
WNcnyaq increment operators. In each, x is incremented byleachtime. In this simpleform, using 
either prefix or postfix works the same way. 

In the second part of this example, you use the expression y = x++, in which the postfix 
increment operator isused. I nthisresult,thevalueofxisincremented after that valueisassigned 
toy. H ence the result: y isassigned theoriginal valueofx (0), and then x isincremented by 1. 

I n thethird part, you usethepref ix expression y = ++x. H ere, the reverse occurs: x isincremented 
before its value isassigned to y . Because x is 1 from the previous step, its value is incremented 
(to 2), and then that valueisassigned to y . Both x and y end up being 2. 



T echnical N ote: T echnically, this description is not entirely correct. I n reality, J ava 
always completely evaluates all expressions on the right of an expression before 
assigning that value to a variable, so the concept of "assigning x to y before x is 
incremented" isn’t precisely right. Instead, Java takes the valueofx and "remem- 
bers" it, evaluates (increments) x, and then assigns the original valueofx to y. 
Although in most simple cases this distinction may not be important, for more 
complex expressions with side effects it may change the behavior of the expression 
overall. See the Language Specification for many more details about the details of 
expression evaluation in Java. 



Comparisons 

J ava has several expressions for testing equality and magnitude. All of these expressions return 



a boolean value (that is, true or false). T able 3.5 shows the comparison operators: 

Table 3.5. Comparison operators. 


0 perator 


Meaning 


Example 


== 


Equal 


X == 3 


! = 


N ot equal 


x != 3 


< 


Less than 


x < 3 


> 


G reater than 


x > 3 


* 


Less than or equal to 


x < 3 


> 


Greater than or equal to 


x > 3 
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Logical Operators 

Expressions that result in boolean values (for example, the comparison operators) can be 
combined by using logical operators that represent the logical combinationsAND, or, xor, and 
logical not. 

For and combinations, use either the& or &&. The expression will betrueonly if both operands 
testsarealsotrue; if either expression isfalse, theentireexpression isfalse.T hedifferencebetween 
the two operators is in expression evaluation. Using&, both sidesoftheexpression areevaluated 
regardlessof theoutcome. U sing&&, if theleftsideof theexpression isfalse, theentireexpression 
returns false, and the right side of the expression is never evaluated. 

F or or expressions, useeither ; or ; ; . or expressionsresult in trueif either or both oftheoperands 
is also true; if both operands are false, the expression is false. As with & and &&, the single ; 
evaluates both sidesoftheexpression regardlessof theoutcome; with ; ;, if the left expression 
is true, the expression returns true and the right side is never evaluated. 

I n addition, thereisthexoR operator ", which returnstrue only if itsoperandsaredifferent (one 
true and one false, or vice versa) and false otherwise (even if both are true). 

In general, only the&& and ; ; arecommonly used asactual logical combinations. &, j, and ~ are 
more commonly used for bitwise logical operations. 

For not, use the i operator with a single expression argument. The value of the not expression 
is the negation of theexpression; if x is true, ix isfalse. 

B it wise O perators 

Finally, here’sashort summary of thebitwiseoperatorsinjava. These are all inherited from C 
and C-H-and areused to perform operationson individual bitsin integers. This book does not 
go into bitwise operations; it’san advanced topic covered better in books on C or C++. Table 
3.6 summarizes the bitwise operators. 

Table 3.6. Bitwise operators. 

Operator Meaning 

& Bitwise and 

i Bitwise or 

Bitwise xor 

« Left shift 

» Right shift 

>» Zero fill right shift 



continues 




Table 3.6. continued 



0 perator 


Meaning 


- 


Bitwise complement 


«= 


Left shift assignment (x =x «y) 


»= 


Right shift assignment (x =x »y) 


»>= 


Zero fill right shift assignment (x =x »>y) 


x&=y 


and assignment (x = x& y) 


x|=y 


or assignment (x+x|y) 


x~ = y 


not assignment (x =x A y) 



Operator Precedence 

Operator precedence determines the order in which expressions are evaluated. This, in some 
cases, can determine the overall value of the expression. For example, take the following 
expression: 

y = 6 + 4 / 2 

Depending on whether the6 + 4 expression orthe4 2 expression devaluated first, the value 
of y can end up beings or 8. Operator precedence determines the orderin which expressions 
are evaluated, so you can predict the outcome of an expression. In general, increment and 
decrement areevaluated beforearithmetic, arithmetic expressionsareevaluated before compari- 
sons, and comparisons are evaluated before logical expressions. Assignment expressions are 
evaluated last. 

T able 3.8 shows the specific precedence of the various operators in J ava. 0 perators further up 
in the table are evaluated first; operators on the same line have the same precedence and are 
evaluated left to right based on how they appear in theexpression itself. For example, give that 
sameexpressiony = 6 + 4 2, you now know, according to thistable, that division devaluated 
before addition, so the value of y will be 8. 

Table 3.7. Operator precedence. 

Operator Notes 

.no Parentheses () group expressions; dot (.) is used for access to 

methods and variables within objects and classes (discussed 
tomorrow); [] is used for arrays (discussed later on in the week) 
++--!- instanceof Returns true or false based on whether the object is an instance 
of the named class or any of that class’s superclasses (discussed 
tomorrow) 



0 perator 

new ( type)expression 



Notes 



The new operator is used for creating new instances of classes; () 
in this case is for casting a value to another type (you’ll learn 
about both of these tomorrow) 

* -f % M ultiplication, division, modulus 

+ - Addition, subtraction 

« » »> Bitwise left and right shift 

< > < > Relational comparison tests 

== i = Equality 

& AND 

XOR 

; or 

&& Logical and 

1 1 Logical or 

? : Shorthand for if .. .then. . .else (discussed on Day 5 ) 

= += -= *= ^-= %= '= Various assignments 



Y ou can al ways changetheorder in which expressionsareevaluated by usi ng parenthesesaround 
the expressions you want to evaluate first. You can nest parentheses to make sure expressions 
evaluate in the order you want them to (the innermost parenthetical expression is evaluated 
first). Thefollowing expression results in a value of 5, because the 6 + 4 expression devaluated 
first, and then the result of that expression (10) is divided by 2: 

y = (6 + 4) / 2 

Parentheses also can beuseful in cases where the precedence of an expression isn’t immediately 
clear— in other words, they can makeyour codeeasierto read. Adding parenthesesdoesn't hurt, 
so if they help you figure out how expressionsareevaluated, go ahead and use them. 

Str i ng A r ith meti c 

One special expression injavaistheuseof the addition operator (+) to create and concatenate 
strings. In most of the previous exam pies shown today and in earlier lessons, you’ve seen lotsof 
lines that looked something like this: 

System. out. println( name + " is a " + color " beetle"); 

T heoutput of that line(to thestandard output) isasinglestring, with thevaluesofthevariables 
(here, name and color), inserted in the appropriate spots in thestring. So what’sgoingon here? 





T he + operator, when used with strings and other objects, creates a single string that contains 
theconcatenation of all itsoperands. If any of theoperandsin string concatenation isnotastring, 
it is automatically converted to a string, making it easy to create these sorts of output lines. 



Technical Note: An object or type can be converted to a string if you implement 
the method tostringo. All objects have a default string representation (the name 
of the class followed by brackets), but most classes override tostringo to provide a 
more meaningful printable representation. 



String concatenation makeslines such as thepreviousoneespeci ally easy to construct. To create 
astring, just add all thepartstogether — thedescriptionsplusthevariables — and output it to the 
standard output, to the screen, to an applet, or anywhere. 

The+= operator, which you learned about earlier, also worksfor strings. For example, take the 
following expression: 

my Name += " Jr."; 

T his expression is equivalent to this: 

myName = myName + " Jr."; 

just as it would be for numbers. I n this case, it changes the value of myName (which might be 
something likejohn smith to have a jr. attheend (John smith jr.). 



Summary 

Asyou learned in thelast two lessons, aj ava program ismadeup primarily of classes and objects. 
Classes and objects, in turn, are made up of methods and variables, and methods are made up 
of statements and expressions. It is those last two things that you’ve learned about today; the 
basic building blocksthat enableyou to create cl asses and methodsand build them up toafull- 
fl edged Java program. 

T oday, you learned about variables, how to declare them and assign valuesto them; literalsfor 
easily creating numbers, characters, and strings; and operators for arithmetic, tests, and other 
simpleoperations. W ith this basic syntax, you can moveon tomorrow to learning about working 
with objects and building simple useful Java programs. 

T o finish up thissummary,Table3.8isa list of all theoperatorsyou learned about today so that 
you can refer back to them. 



Table 3.8. Operator summary. 



Operator Meaning 

+ Addition 

Subtraction 

* M ultiplication 

Division 

% Modulus 

< Less than 

> G reater than 

^ Less than or equal to 

^ Greater than or equal to 

== Equal 

§» N ot equal 

&& Logical and 

1 1 Logical or 

i Logical not 

& AND 

| OR 

XOR 

« Left shift 

» Right shift 

»> Zero fill right shift 

Complement 
Assignment 
++ I ncrement 

D ecrement 

+= Add and assign 

Subtract and assign 
*= M ultiply and assign 

-^= Divide and assign 

%= M odulus and assign 

&= and and assign 




Table 3.8. continued 



0 perator 


Meaning 


! = 


or and assign 


«= 


Left shift and assign 


»= 


Right shift and assign 


»>= 


Zero fill right shift and assign 



Q&A 

Q I didn't see any way to define constants 

A You can't create local constants in J ava; you can create only constant instance and class 
variables. You’ll learn how to do this tomorrow. 

Q What happens if you declare a variable to be some integer type and then give it a 
number outside the range of values that variable can hold? 

A Logically, you would think that the variable is just converted to the next larger type, 
but this isn't what happens. What does happen is called overflow. This means that if a 
number becomes too big for its variable, that number wraps around to the smallest 
possible negative number for that type j/Fstarts counting upward toward zero again. 
Because this can result in some very confusing (and wrong) results, make sure that you 
declare the right integer type for all your numbers. I f there's a chance a number will 
overflow its type, use the next larger type instead. 

Q H ow can you find out the type of a given variable? 

A If you’re using the base types (mt, float, boolean), j/Fso on, you can’t. If you care 
about the type, you can convert the value to some other type by using casting (you’ll 
learn about this tomorrow). 

If you’re using class types, you can usetheinstanceof operator, which you’ll learn 
more about tomorrow. 

Q Why does Java have all these shorthand operators for arithmetic and assignment? 
It's really hard to read that way. 

A The syntax of Java is based on C++, jnd therefore on C. 0 ne of C’s implicit goals is 
the capability of doing very powerful things with a minimum of typing. Because of 
this, shorthand operators, such as the wide array of assignments, are common. 
There'sno rulethat says you have to use these operators in your own programs, 
however. If you find your code to be more readable using the long form, no one will 
come to your house and make you change it. 
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Working with Objects 



L et's start today's I esson with an obviousstatement: becausej avaisan object-oriented language, 
you’re going to be dealing with a lot of objects. You’ll create them, modify them, move them 
around, change their variables, call their methods, combinethem with other objects— and, of 
course, develop classes and use your own objects in the mix. 

T oday, therefore, you’ll learn all about the J ava object in its natural habitat. T oday’s topics 
include: 

fl Creating instances of classes 

Z T esting and modifying class and instance variables in your new instance 

□ Calling methods in that object 

□ Casting (converting) objects and other data types from one class to another 

□ 0 ther odds and ends about working with objects 

□ An overview of the Java class libraries 



Creating New Objects 

W hen you writeaj ava program, you definea set of classes. Asyou learned on D ay 2, classes are 
templatesforobjects;forthemost part, you merely usetheclasstocreateinstancesand then work 
with those instances. I n thissection, therefore, you’ll learn how to createa new object from any 
given class. 

Remember strings from yesterday?You learned that using a string literal— a series of characters 
enclosed in double-quotes— creates a new instance of the class string with the value of that 
string. 

T he string class is unusual in that respect— although it’s a class, there’s an easy way to create 
instancesof that classusingaliteral. T heotherclassesdon't havethat shortcut; tocreateinstances 
of those classes you have to do so explicitly by using the new operator. 



Note: W hat about the literals for numbers and characters? D on’t they create 
objects, too? Actually, they don’t. The primitive data types for numbers and 
characters create numbers and characters, but for efficiency, they aren’t actually 
objects. You can put object-wrappers around them if you need to treat them like 
objects (you’ll learn how to do this later). 
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Using new 

T o create a new object, you use new with the name of the class you want to create an instance 
of, then parentheses after that: 

String str = new StringO; 

Random r = new Random(); 

Motorcycle m2 = new Motorcycle () 

T he parentheses are important; don't leave them off. T he parentheses can be empty, i n which 
case the most simple, basic object is created, or the parentheses can contain arguments that 
determine the initial values of instance variables or other initial qualities of that object. The 
number and type of arguments you can use with new are defined by the class itself by using a 
special method called a constructor; you’ll learn about how to create constructors in your own 
classes later on this week. 




Caution; Some classes may not enable you to create instances without any argu- 
ments. C heck the class to make sure. 



For example, take the Date class, which creates date objects. Listing 4.1 is a Java program that 




Output 



Date 1 
Date 2 
Date 3 



Sun Nov 26 19:10:56 PST 1995 
Sun Aug 01 07:30:00 PDT 1971 
Sat Apr 03 15:24:00 PST 1993 





Working with Objects 



lAnaivdd 1 n thisexam P |e - three different dates are created by using different arguments to new. T he 
Hlldlyab fj rs t instance (line 8) uses new with no arguments, which creates a Date object for today’s 
date (as the first line of the output shows). 

T he second Date object you create in this example has five integer arguments. T he arguments 
represent a date: year, month, day, hours, and seconds. And, as the output shows, thiscreates 
a Date object for that particular date: Sunday, August first, 1971, at 7:30 AM . 

The third version of Date takes one argument, a string, representing the date as a text string. 
W hen the Date object iscreated, that string isparsed, and aDate object with that dateand time 
iscreated (seethethird lineof output). Thedatestring can takemany different formats; seethe 
API documentation for the Date class (part of the java.utii package) for information about 
what strings you can use. 

What new Does 

W hat doesnew do?W hen you usethenew operator, several thingshappen: first, thenew instance 
of thegiven cl ass is created, and memory isallocated for it. I n addition (and most importantly), 
when thenew object iscreated, aspecial method defined in thegiven classiscalled. T hisspecial 
method is called a constructor. 

NEW*~ Constructors are special methods for creating and initializing new instances of classes. 
TERM Constructorsinitializethenew object and itsvariables, createany other objectsthat object 
needs, and generally perform any other operations the object needs to run. 

M ultiple constructor definitions in a class can each have a different number or type of 
arguments— then, when you usenew, you can specify different arguments in the argument list, 
and the right constructor for those argu ments wi 1 1 be cal I ed . T hat’s how each of those different 
versions of new that were listed previously can create different things. 

When you create your own classes, you can define as many constructors as you need to 
implement that class’s behavior. You’ll learn how to create constructors on Day 7. 

A Note on Memory Management 

M emory management in J ava is dynamic and automatic. W hen you create a new object in J ava, 
J ava automatically allocates the right amount of memory for that object i n the heap. Y ou don’t 
have to allocate any memory for any objects explicitly; J ava does it for you. 

W hat happenswhenyou’refinished with that object?H ow do you de-allocatethe memory that 
object uses? The answer is again: memory management is automatic. 0 nee you finish with an 
object, that object no longer has any live references to it (it won’t be assigned to any variables 
you’restill using orstored in any arrays). J ava hasagarbagecollectorthat looksfor unused objects 
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and reclaims thememory that thoseobjectsareusing. You don’t have to do any explicit freeing 
of memory; you just have to make sure you’re not still holding onto an object you want to get 
rid of. You’ll learn more specific details about the Java garbage collector and how it works on 
Day 21. 

Accessing and Setting Class and 
I nstance Variables 

N ow you haveyour very own object, and that object may havedassor instance variablesdefined 
in it. H owdoyou work with thosevariables?Easy! C lassand instance variables behavein exactly 
the same ways as the local variables you learned about yesterday; you just refer to them slightly 
differently than you do regular variables in your code. 



Getting Values 

To get at the value to an instance variable, you use dot notation. 

NEW*' With dot notation, an instance or class variablename has two parts: the object on the left 
TERM side of the dot, and the variable on the right side of the dot. 

For example, if you havean object assigned to thevariablemyobject, and that object hasavariable 
called var, you refer to that variable’s value like this: 




myObject.var; 

This form for accessing variables is an expression (it returns a value), and both sides of the dot 
are also expressions. This means that you can nest instance variable access. If that var instance 
vari ableitself holdsan object, and that object has itsown instance variablecalled state, you can 
refer to it like this: 



myOb j ect . var . state ; 

Dotexpressionsareevaluatedleftto right, so you start with myobject’svariable var, which points 
to another object with the variable state. You end up with the value of that state variable. 



Changing Values 

Assigning a valueto that vari able isequally easy— just tack an assignment operator on theright 
side of the expression: 

myObject.var. state = true; 
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Listing 4.2 isan example of a program that tests and modifies the instance variables in apoint 
object, point ispartofthejava.awt package and refers to a coordinate point with an x and a y 
value. 



Type 



Listing 4.2. The TestPoint Class. 



1: import java.awt. Point; 
2: 

3: class TestPoint { 



6 

7 

8 
9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 



public static void main (String args [ ] ) { 
Point thePoint = new Point (10,10) ; 

System. out. println("X is " + thePoint. x); 
System. out. println("Y is " + thePoint. y); 

System. out. println( "Setting X to 5."); 
thePoint. x = 5; 

System. out. println( "Setting y to 15."); 
thePoint. y = 15; 

System. out. println("X is " + thePoint. x); 
System. out. println("Y is " + thePoint. y); 



Output 



X is 10 
Y is 10 

Setting X to 5. 
Setting y to 15. 




Analysis 



I n thisexample, you first createan instanceof point wherexand y are both 1 0 (Iine6). Lines 
8 and 9 print out thoseindividual values, and you can see dot notation at work there. Lines 

II through 14changethevaluesofthosevariablestosand 15, respectively. Finally, lines 
16 and 17 print out the values of x and y again to show how they’ve changed. 



Class Variables 

Cl ass variables, as you learned before, are variables that are defined and stored in the class itself. 
T heir values, therefore, apply to the class and to all its instances. 

With instance variables, each new instanceof thedassgetsa new copy of theinstance variables 
that class defines. Each instance can then change the values of those instance variables without 
affecting any other instances. W ith class variables, there isonly one copy of that variable. Every 
i nstance of the class has access to that variable, but there is only one val ue. C hangi ng the val ue 
of that variable changes it for all the instances of that class. 
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You defineclassvariablesby including thestatic keyword before the var i ab I e i tsel f . You’ll learn 
more about this on Day 6. For example, take the following partial class definition: 

class FamilyMember { 

static String surname = "Johnson"; 

String name; 
int age; 



I nstancesof the class FamilyMember each have their own values for name and age. But the class 
variablesumame hasonlyonevaluefor all family members. C hangesumame, and all theinstances 
Of FamilyMember are affected. 

T o access class variables, you use the same dot notation as you do with instance variables. T o 
get or change the value of the class variable, you can use either the instance or the name of the 
class on the left side of the dot. Both the li nes of output in this example print the same value): 

FamilyMember dad = new FamilyMember () 

System. out. println("Family's surname is: " + dad . surname) ; 

System. out. println(" Family's surname is: " + FamilyMember. surname ) ; 

Because you can use an instance to change the value of a class variable, it’s easy to become 
confused about class variables and where their values are coming from (remember, thevalueof 
a cl ass variable affects all theinstances). For this reason, it’s a good idea to use the name of the 
class when you refer to a class variable— it makes your code easier to read and strange results 
easier to debug. 

Calling Methods 

Calling a method in objects issimilar to referringto its instance variables: method callsalso use 
dot notation. The object whose method you’re calling is on the left side of the dot; the name 
of the method and its arguments is on the right side of the dot: 

myObject.methodOne(arg1 , arg2, arg3); 

N otethatall methodsmusthaveparenthesesafterthem, even if that method takesno arguments: 

myOb j ect . methodNoArgs ( ) ; 

If the method you’ve called results in an object that itself has methods, you can nest methods 
as you would variables: 

myOb j ect . getClass ( ) . getName ( ) ; 

You can combine nested method calls and instance variable references as well: 



myObject.var.methodTwo(arg1 , arg2) ; 
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system . out . printin ( ) , the method you’ve been using all through the book this far, is a great 
example of nesting variables and methods. The system class (part of the java.iang package) 
describes system-specific behavior, system, out isadassvariablethatcontainsan instanceofthe 
class printstream that pointsto thestandard output of the system, pnintstream instances have 
a printin ( ) method that prints a string to that output stream. 



Listing 4.3 shows an example of calling some methods defined in the string class. Strings 
include methodsfor string tests and modification, similar to what you would expectin a string 
library in other languages. 




O i I The string is: Now is the winter of our discontent 
UtDUt Len 9 th of this string: 35 

The character at position 5: s 

The substring from positions 11 to 18: winter 

The index of the character d: 25 

The index of the beginning of the substring "winter": 11 
The string in upper case: NOW IS THE WINTER OF OUR DISCONTENT 




In line 4, you create a new instance of string by using a string literal (it’s easier that way 
than using new and then putting the characters in individually). The remainder of the 
program simply calls different string methods to do different operations on that string: 



□ Line 6 prints the value of the string we created in line 4: “now is the winter of our 
discontent". 
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D Line 7 calls the length o method in the new string object. Thisstring has35 charac- 
ters. 

□ Line 9 calls the charAto method, which returns the character at the given position in 
the string. N otethat string positions start at a, so the character at position 5 is s. 

dt Unell calls the substring 0 method, which takes two integersindicatingarangeand 
returns the substring at those starting and ending points. The substring 0 method 
can also be called with only one argument, which returns the substring from that 
position to the end of the string. 

□ Line 13 calls the mdexoto method, which returns the position of the first instance of 
the given character (here, 1 d ■ ). 

□ Line 15 shows a different use of theindexot 0 method, which takes a string argument 
and returns the index of the beginning of that string. 

El Finally, line 18 uses the touppercaseo method to return a copy of the string in all 
uppercase. 

Class Methods 

Class methods, like cl ass variables, apply to the class as a whole and not to its instances. Class 
methods are commonly used for general utility methods that may not operate directly on an 
instanceof that class, but fit with that class conceptually. For example, thestnng cl ass contains 
a class method called vaiueof 0 , which can take one of many different types of arguments 
(integers, booleans, other objects, and so on). The vaiueof 0 method then returns a new 
instanceof string containing thestring vaiueof theargument it wasgiven.Thismethod doesn’t 
operatedirectlyonan exi sting instanceof string, but getting a string from another object ordata 
type is definitely a string-like operation, and it makes sense to define it in thestring class. 

Classmethodscan also beuseful for gathering general methodstogetherinoneplace(thedass). 
For example, the Math class, defined in the java.iang package, contains a large set of 
mathematical operationsasdassmethods- there arenoinstancesofthedassMath, but you can 
still use its methods with numeric or boolean arguments. 

T 0 call adassmethod, usedot notation asyou do with instance methods. Aswith cl ass variables, 
you can use either an instanceof thedass or the class itself on the left site of the dot. H owever, 
for the same reasons noted in the discussion on class variables, using the name of the class for 
dassvariablesmakesyour codeeasierto read. T helast two linesin thisexampleproducethesame 
result: 

String s, s2; 
s = "too" ; 
s2 = s.valueOf (5) ; 
s2 = String.valueOf (5) ; 
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References to Objects 

Asyou work with objects, oneimportantthing going on behind thescenesistheuseof references 
to thoseobjects. W hen you assign objects to variables, or passobjectsasargumentsto methods, 
you are passing referencesto thoseobjects, not theobjectsthemselvesorcopiesof thoseobjects. 

An example should make this clearer. Examine the following snippet of code: 

import java.awt. Point; 

class ReferencesTest { 

public static void main (String args[]) { 

Point ptl, pt2; 

ptl = new Point(100, 100); 

pt2 = ptl ; 



ptl .x = 200; 
ptl .y = 200; 

System. out. println( "Pointl : " + ptl.x + ", " + ptl.y); 

System. out. println("Point2: ■ + pt2.x + ", " + pt2.y); 

} 

> 

In this program, you declare two variables of type point, and assign anew Point object to pti. 
T hen you assign the value of pti to pt2. 

Now, here’s the challenge. After changing pti 'Sx and y instance variables, what will pt2 look 
like? 



H ere’s the output of that program: 

Hlltnilf Pointl: 200, 200 

Point2: 200, 200 

a „ J.J. Asyou can see, pt2 wasalso changed. W hen you assign thevalueof pti to pt2, you actually 

nlldiya^ cr eate a reference from P 2 to the same object to which pti refers. C hange the object that 
pt2 refersto, and you also changethe object that pti points to, because both are references 
to the same object. 



Figure 4.1. 

References 




Point object 



x: 200 
y: 200 



T he fact that J ava uses references becomes particularly important when you pass arguments to 
methods. You’ll learn more about this later on today, but keep these references in mind. 
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Technical Note: There are no explicit pointers or pointer arithmetic in Java— just 
^references. H owever, because of J ava references, you have most of the capabilities 
it you have with pointers without the confusion and lurking bugs that explicit 
pon|ers can create. 



Casting andtConverting Objects and 
Primitive Types 

Sometimesin yourj avapro^^kjou may have a value stored somewherethat isthewrongtype. 
M aybeit’san instance of the wrong class, or perhaps it’s a float and you want it to bean mt, 
or it’s an integer and you want it to be a string. T o convert the value of one type to another, you 
use a mechanism called casting. 

NEW** Castingisa mechanism of convertiTl^^alueof an object or primitivetype into another 
TERM type. T he result of acast isanew obje ^^ ^i_e: casting doesnot affect theoriginal object 
or value. 



Although theconcept of casting isasimpleone, tns 
to what other types are complicated by the fact that^ 
boolean), and Object typesfstring, Point, Window, and S 
are three forms of casts and conversions to talk about ini 



^whattypesinjavacan beconverted 
k ^both primitivetypesfint, float, 
•auseof thesethree types, there 



B Casting between primitive types: mt to float to booieU 
□ C asting between object types: an instance of a class to an ill 
O Converting primitive types to objects and then extracting prirTI 
those objects 



Ifif another class 
|lues back out of 



Casting Primitive Types 

Casting between primitive types enables you to "convert" the value of one type to^Mher 
primitive type- for example, to assign a number of one type to a variable of anoth^^^, 
C asting between primitive typesmost commonly occurswith the numeric types; boolean val^ 
cannot be cast to any other primitivetype. You can, however, cast i or 0 to boolean values. 



Often, if thetypeyou are casting to is"larger" than the typeof thevalueyou're converting, you 
may not have to use an explicit cast. You can often automatically treat a byte or a character as 
an mt, for example, or an mt asaiong, an mt asafioat, or anything asadoubie automatically. 
In this case, because the larger type provides more precision than the smaller, no loss of 
information occurs when the value is cast. 
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T o convert a large valueto smaller type, you must use an explicit cast, because converting that 
value may result in a loss of precision. Explicit casts look like this: 

( typename ) value 

In this form, typename is the name of the type you’re converting to (for example: short, mt, 
float, boolean), and value is an expression that results in the value you want to convert. This 
expression divides the values of x by the value of y and casts the result to an mt: 

(int) (x / y); 

N otethat because the precedence of casting is higher than that of arithmetic, you have to use 
parentheses so that the result of the division is what gets cast to an mt. 

Casting Objects 

Instances of classes can also be cast to instances of other classes, with one restriction: the class 
of theobject you’re casting and theclassyou'recasting itto must be related by inheritance; that 
is, you can cast an object only to an instanceof itsdass’ssub- or superclass— not to any random 
class. 

Analogousto converting a primitive valueto a larger type, some objectsmay not need to be cast 
explicitly. In particular, because instances’ subclasses usually contain all the information that 
instances' superclasses do, you can use an instanceof asubclassanywhereasuperclassisexpected. 
Suppose you have a method that takes two arguments: one of type object, and one of type 
Number. You don’t haveto passinstancesof thoseparticular cl assesto that method. Fortheobject 
argument, you can pass any subclass of object (any object, in other words), and fortheNumber 
argument you can pass in any instanceof any subclass of Number (integer, Boolean, Float, and 
so on). 

Casting an object to an instanceof one of that object’s superclasses loses the information the 
original subclass provided and requiresaspecific cast. T o cast an object to another class, you use 
the same casting operation that you used for base types: 

(classname) object 

In this case, ciassname is the name of the class you want to cast theobject to, and object is a 
reference to theobject you’re casting. N otethat casting createsa new instanceof the new class 
with all the information that theold object contained; theold object still continues to exist as 
it did before. 

H ere'sa (fictitious) exampleof acast of an instanceoftheclassGreenAppietoan instanceof the 
class Apple (where GreenAppie is theoretically a subclass of Apple): 

GreenApple a; 

Apple a2; 
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a = new GreenAppleO ; 
a2 = (Apple) a; 

I n addition to casting objectsto classes, you can also cast objects to interfaces- but only if that 
object’s class or one of its superclasses actually implements that interface. Casting an object to 
an interfacethen enablesyou to call oneof that interface’smethodseven if that object'sdassdoes 
not directly implement that interface. You’ll learn more about interfaces in Week 3. 

Converting Primitive Types 
to O bjects and Vice Versa 

N ow you know how to cast a primitive type to another primitive type and how to cast between 
classes. H ow can you cast one to the other? 

You can’t! Primitive types and objects are very different things in Java and you can’t 
automatically cast or convert between thetwo. H owever, the j ava . iang package includes several 
special classes that correspond to each primitive data type: integer for mts, Float for floats, 
Boolean for booleanS, and SO On. 

U sing class methods defined in these classes, you can create an object-equivalent for all the 
primitivetypesusingnew.Thefollowinglineofcodecreatesan instanceofthemtegerdasswith 
the value 35: 

Integer intObject = new Integer(35); 

0 nee you have actual objects, you can treat those values as objects. Then, when you want the 
primitive values back again, there are methods for that as well— for example, themtvaiueo 
method extracts an mt primitive value from an integer object: 

int thelnt = intObject. intValue() ; // returns 35 

See the Java API documentation for these special classes for specifics on the methods for 
converting primitives to and from objects. 

Odds and Ends 

This section is a catchall for other information about working with objects, in particular: 
jQf Comparing objects 

□ Copying objects 

□ Finding out the class of any given object 

fcl Testing to see whether an object isan instance of a given class 
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Comparing O bjects 

Yesterday, you learned about operatorsfor comparing values: equals, not equals, less than, and 
soon.M ostoftheseoperatorsworkonlyon primitive types, not on objects. If you try to useother 
values as operands, thejava compiler produces errors. 

T heexception tothisruleiswith theoperatorsfor equality: == (equal) and i= (not equal). These 
operators, when used with objects, tests whether the two operands refer to exactly the same 
object. 

What should you do if you want to be able to compare instances of your class and have 
meaningful results?You haveto implement special methods in your class, and you have to call 
those methods using those method names. 



T echnical N ote: J ava does not have the concept of operator overloading- that is, 
the capability of defining the behavior of the built-in operators by defining meth- 
ods in your own classes. The built-in operators remain defined only for numbers. 



A good example of this is the string class. It is possibleto have two strings, two independent 
objects in memory with the same values- that is, the same characters in the same order. 
According to the == operator, however, those two string objects will not be equal, because, 
although their contents are the same, they are not the same object. 



The string class, therefore, defines a method called equaiso that tests each character in the 
string and returns true if the two strings have the same values. Listing 4.4 illustrates this 
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Listing 4.4. A Test of String Equality. 
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class EqualsTest { 

public static void main (String args[]) { 

String strl, str2; 

strl = "she sells sea shells by the sea shore."; 
str2 = strl ; 

System. out. println( "Stringl : " + strl); 

System. out. println("String2: " + str2); 

System. out. printing "Same object? " + (strl == str2)); 

str2 = new String(str1 ) ; 
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System. out. println( "Stringl : " + strl); 

System. out. printing "String2: " + str2); 

System. out. println( "Same object? " + (strl == str2)); 
System. out. println( "Same value? " + strl .equals(str2) ) ; 




a jl jl Stringl : she sells sea shells by the sea shore. 

UUUJUG String2: she sells sea shells by the sea shore. 

Same object? true 

Stringl: she sells sea shells by the sea shore. 

String2: she sells sea shells by the sea shore. 

Same object? false 
Same value? true 



■ The first part of this program (lines 4 through 6) declares two variables, stri and str 2 , 
fSS assignsthe literal she sens sea shells by the sea shore, to stri, and then assignsthat 
value to str 2 . Asyou know from object references, now stri and str 2 point to thesame 
object, and the test at line 10 proves that. 

I n the second part, you create a new string object with the value of stri . N ow you have two 
different string objects with thesame value. T esting them to seewhether they’rethesameobject 
by using the == operator (line 16) returns the expected answer, as does testing them using the 
equals method (line 17) to compare their values. 



Technical Note: Why can’t you just use another literal when you change str 2 , 
rather than using new? String literals are optimized in Java— if you create a string 
using a literal, and then use another literal with the same characters, J ava knows 
enough merely to give you the first string object back. Both strings are the same 
objects- to create two separate objects you have to go out of your way. 




Copying Objects 

Recall from the section on object references that assigning variables and passing objects as 
arguments to methods affect only the object’s reference and doesn't create copies of those 
objects. H ow do you create copiesofobjects?There are two ways: thecopyo method and the 
cioneo method. 

T hecopy < > method (defined in obj ect, and so availableto all objects), takesasingleargument— 
another instanceofthesamedass- and copiesthevaluesof all theargument'sinstance variables 
into the instance variables of the current object (the one in which you’re calling the method). 
N otethat if those instance variables in turn hold references to objects, only the references are 
copied, not the objects. 

Point ptl , pt2 , pt3; 
ptl = new Point(0,0) ; 
pt2 = new Point(100, 100) ; 

pt2.copy(pt1 ) ; // ptl's values are copied into pt2; both now are (0,0). 
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T hecione ( ) method issimilar to copy ( ) , except that clone < > takes no arguments. T hecione ( ) 
method createsanew instance of the same class as the source object and then copies the values 
of the instance variables (either primitive types or referencesto other objects), clone o returns 
an instance of the class object; to use it as an instance of the original class you have to cast it. 
H ere'san example that clones the point object in P t2 and stores the result in P t3: 

P t3 = (Point) P t2.clone(); 

Determining the Class of an Object 

W ant to find out the class of an object? H ere’s the way to do it for an object assigned to the 
variable obj: 

String name = obj .getClass() .getName() ; 

W hat doesthisdo?Thegetciasso method isdefined in theobject class, and as such isavailable 
for all objects. The result of that method is a class object (where class is itself a class), which 
hasamethod called getNameo. getNameo returns a string representing the name of the class. 

Another test that might be useful to you is the mstanceof operator, instanceof has two 
operands: an object on the left, andthenameofadassontheright.Theexpression returnstrue 
or false based on whether the object is an instance of the named class or any of that class’s 
superclasses: 

"foo" instanceof String // true 
Point P t = new Point ( 1 0, 1 0) ; 

P t instanceof String // false 

T he instanceof operator can also be used for interfaces; if an object implements an interface, 
the instanceof operator with an interface name on the right side returns true. You’ll learn all 
about interfaces in Week 3. 

The J ava Class Libraries 

T o finish up today, let's look at the some of thej ava class libraries. Actually, you’ve had some 
experience with them already, so they shouldn't seem that strange. 

The Java class libraries provide the set of classes that are guaranteed to be available in any 
commercial Java environment (for example, in H otj ava or in N etscape 2.0). Those classes are 
in the java package and include all the classes you’ve seen so far in this book, plus a whole lot 
more classes you'll learn about later on in this book (and more you may not learn about at all). 

The Java Developer's Kit comes with documentation for all the Java class libraries, which 
includesdescri ptionsof each cl ass’s instance variables, methods, constructors, interfaces, and so 
on. A shorter summary of thej ava API isin Appendix B aswell. Exploring thej avaclasslibraries 
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and their methodsand instance variables is a great way to figure out what Java can and cannot 
do, as well as a starting point for your own development. 

H ere are the class packages that are part of thejava class libraries: 

□ java.iang: Classesthat apply to the language itself, which includes the object class, 
the string class, and the system class. It also contains the special classes for the 
primitive types (integer, Character, Float, and SO On). 

O java.utii: U tility classes, such as Date, as well as simple collection classes, such as 
Vector and Hashtable. 

Ef java.io: Input and output classes for writing to and reading from streams (such as 
standard input and output) and for handling files. 

□ java.net: Classes for networking support, including socket and url (a class to 
represent references to documents on the World Wide Web). 

;lfif java.awt: (the Abstract W indow Toolkit): Classes to implement a graphical user 
interface, including classes for window, Menu, Button, Font, checkBox, and so on. This 
package also includes classes for processing images (the java.awt. image package). 

□ java. applet: Classes to implement J ava applets, including the Applet class itself, as 
well astheAudiocnp class. 

In addition to thejava classes, your development environment may also include additional 
classesthat provideother utilitiesorfunctionality. Although theseclassesmay beuseful, because 
they are not part of the standard J ava library, they won’t be available to other people trying to 
run your J ava program. T his is particularly important for applets, because applets are expected 
to be able to run on any platform, using any Java-aware browser. 0 nly classes inside the java 
package are guaranteed to be available on all browsers and Java environments. 

Summary 

0 bjects, objects everywhere. T oday, you learned all about how to deal with objects: how to 
create them, how to find out and change the values of their variables, and how to call their 
methods. Y ou also learned how to copy and comparethem, and how to convert them into other 
objects. Finally, you learned a bit about thejava class libraries- which give you a whole slew of 
classes to play with in your own programs. 

You now have the fundamentals of how to deal with most simple things in thejava language. 
All you have left are arrays, conditionals, and loops, which you'll learn about tomorrow. Then 
you’ll learn how todefineand usedassesinjavaapplicationson Day 6, and launch directly into 
appletsnext week. W ith just about everythingyou do in yourj ava programs, you’ll alwayscome 
back to objects. 
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Q&A 

Q I 'm confused about the differences between objects and the primitive data types, 
such asint and boolean. 

A The primitive types in the language (byte, short, mt, long, float, double, and char) 
represent the smallest things in the language. They are not objects, although in many 
ways they can be handled like objects- they can be assigned to variables and passed in 
and out of methods. M ost of the operations that work exclusively on objects, however, 
will not. 

0 bjects usually represent instances of classes and as such, are much more complex 
data types than simple numbers and characters, often containing numbers and 
characters as instance or class variables. 

Q I n the section on calling methods, you had examples of calling a method with a 
different number of arguments each time— and it gave a different kind of result. 
How is that possible? 

A That's called method overloading. Overloading enables the same function name to have 
different behavior based on the arguments it’s called with— and the number and type 
of arguments can vary. W hen you define methods in your own classes, you define 
separate method signatures with different sets or arguments and different definitions. 
When that method is called, J ava figures out which definition to execute based on the 
number and type of arguments with which you called it. 

You’ll learn all about this on Day 6. 

Q No operator overloading in Java? Why not? I thought Java was based on C++, 
and C ++ has operator overloading. 

A Java was indeed based on C++, but it was also designed to be simple, so many of 
C ++’s features have been removed. T he argument against operator overloading is that 
because the operator can be defined to mean anything, it makes it very difficult to 
figure out what any given operator isdoing at any onetime. This can result in entirely 
unreadable code. G iven the potential for abuse, the designers of J ava felt it was one of 
the C ++ features that was best left out. 
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Although you could writejavaprogramsusing what you’velearned so far, thoseprogramswould 
bepretty dull. M uch ofthegood stuff in Java or in any programming language results when you 
have arrays to store values in and control-flow constructs (loops and conditionals) to execute 
different bits of a program based on tests. T oday, you’ll find out about the following: 

□ Arrays, one of the most useful objects in Java, which enableyou to collect objects into 
an easy-to-managelist 

□ Block statements, for grouping together related statements 

□ it and switch, for conditional tests 

□ tor and while loops, for iteration or repeating a statement or statements multiple 
times 

Arrays 

Arraysinjavaaredifferentthan they arein other languages. Arraysin Java are actual objectsthat 
can be passed around and treated just like other objects. 

NEW** Arraysarea way to storea list of items. Each element of thearrayholdsan individual item, 
TERM and you can place items into and remove items from those slots as you need to. 

Arrays can contain any type of value (base types or objects), but you can’t store different types 
in a single array. You can have an array of integers, or an array of strings, or an array of arrays, 
but you can't have an array that contains, for example, both strings and integers. 

T o create an array in J ava, you use three steps: 

1. Declare a variable to hold the array. 

2. C reate a new array object and assign it to the array variable. 

3 . Sto re th i n gs i n th at array . 

Declaring Array Variables 

T hefirst step to creating an array iscreating a variablethat will hold thearray, just asyou would 
any other variable. Array variablesindicatethetypeof object thearray will hold (just as they do 
for any variable) and the name of thearray, followed by empty brackets([ ] ). T hefollowing are 
all typical array variable declarations: 

String diff icultWords[ ] ; 

Point hits[ ] ; 



int temps [ ] ; 




An alternate method of defining an array variable is to put the brackets after the type instead of 
after the variable. They are equivalent, but this latter form i s often much more readable. So, for 
example, these three declarations could be written like this: 

String[] difficultWords; 

Point]] hits; 
int [ ] temps; 

Creating Array Objects 

T hesecond step isto createan array object and assign it to that variable. There are two ways to 
do this: 

dj .Using new 

■O Directly initializing the contents of that array 
T he first way is to use the new operator to create a new instance of an array: 

String!] names = new String [10]; 

T hat linecreatesanew array of stringswith ten slots or elements. W hen you createthenew array 
object using new, you must indicate how many elements that array will hold. 

Array objects can contain primitive types such asintegersor booleans, just as they can contain 
objects: 

int [ ] temps = new int [ 99 ] ; 

W hen you createan array object using new, all its elements are initialized for you (0 for numeric 
arrays, false for boolean, 1 \o ■ for character arrays, and nun for everything else). You can also 
createand initialize an array at thesametime. Instead of usingnew to create the new array object, 
enclose the elements of the array inside braces, separated by commas: 

String[] chiles = { "jalapeno", "anaheim", "serrano," 

"habanero," "thai" }; 

E ach of the elements inside the braces must be of the same type and must be the same type as 
the variable that holds that array. An array the size of the number of elements you’ve included 
will be automatically created for you. This example creates an array of string objects named 
chiles that contains five elements. 

Accessing Array E lements 

O nee you have an array with initial values, you can test and change thevaluesin each slot of that 
array. T 0 get at a value stored within an array, use the array subscript expression: 



myArray [subscript ] ; 
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Th emyArray part of this expression is a variable holding an array object, although it can also be 
an expression that resultsin an array). T h esubscnpt istheslot within thearray to access, which 
can also bean expression. Array subscripts start with 0, as they do in C and C++. So, an array 
with ten elements has array values from subscript 0 to 9. 

N ote th at al I array su bscri pts are ch ecked to m ake su re t hat th ey are i n si d e th e bou n d ari es of th e 
array (greater than 0 but lessthan thearray’slength) either when yourjava program iscompiled 
or when itisrun. It is impossible in Javato accessor assign avalueto an array element outside 
of the boundaries of the array. N ote the following two statements, for example: 

String arr[] = new String [10]; 
arr[10] = "eggplant"; 

A program with that last statement in it produces a compiler error at that line when you try to 
compile it. The array stored in arr has only ten elements numbered from 0, the element at 
subscript 10 doesn't exist, and thejava compiler will check for that. 

If thearray subscript iscalculated at run-time(for example, aspart of aloop) and endsup outside 
theboundariesof thearray, thej ava interpreter also producesan error (actually, to betechnically 
correct, it throws an exception). You’ll learn more about exceptions later on next week and on 
Day 18. 

H ow can you keep from overrunning the end of an array accidentally in your own programs? 
You can test for the length of the array in your programs using the length instance variable — 
it's available for all array objects, regardless of type: 

int len = arr. length // returns 10 

C hanging Array E lements 

T o assign a value to a particular array slot, merely put an assignment statement after thearray 
access expression: 

myarray[1 ] = 15; 
sentence[0] = “The"; 
sentence[l0] = sentence[0]; 

An important thing to note isthat an array of objects in J ava isan array of referencesto those 
objects (similar in some ways to an array of pointers in C or C++). When you assign avalueto 
a slot in an array, you’re creating a reference to that object, just as you do for a plain variable. 
W hen you move values around insidearrays(asin that last line), you just reassign the reference; 
you don’t copy thevaluefrom oneslot to another. Arraysof primitivetypessuch asmtsor floats 
do copy the values from oneslot to another. 

Arrays of references to objects, as opposed to the objects themselves, are particularly useful 
because it means you can have multiple referencesto the same objects both insideand outside 
arrays- for example, you can assign an object contained in an array to avariableand referto that 
same object by using either the variable or the array position. 



Multidimensional Arrays 

Java does not support multidimensional arrays. H owever, you can declare and create an array 
of arrays (and those arrays can contain arrays, and so on, for however many dimensions you 
need), and access them as you would C -style multidimensional arrays: 

int coords [ ] [ ] = new int [ 12] [ 12] ; 
coords[0] [0] = 1 ; 
coords[0] [1 ] = 2; 

B lock Statements 

A block statement isa group of other statements surrounded by braces(O)- Y ou can usea block 
anywhere a single statement would go, and the new block creates a new local scope for the 
statements inside it. This meansthat you can declare and use local variables inside a block, and 
those variableswi II cease to exist aftertheblock isfinished executing. For example, here'sa block 
insidea method definition that declaresanew variabley. You cannot use y outside the block in 
which it’s declared: 

void testblock() { 
int x = 10; 

{ // start of block 
int y = 50; 

System. out. println( "inside the block:"); 

System. out. println("x: 11 + x); 

System. out. println("y: " + y); 

> // end of block 

> 

Blocksarenot usually used in thisway— aloneinamethod definition. You’vemostly seen blocks 
up to this point surrounding class and method definitions, but another very common use of 
block statements is in thecontrol flow constructs you’ll learn about in the remainder of today’s 
lesson. 

if Conditionals 

The if conditional, which enables you to execute different bits of codebased on asimpletest 
in Java, is nearly identical to if statements in C. if conditionals contain the keyword if, 
followed by a boolean test, followed by a statement (often a block statement) to execute if the 
test is true: 

if (x < y) 

System. out. println("x is smaller than y " ) ; 

An optional else keyword provides the statement to execute if the test is false: 

if (x < y) 

System. out. println("x is smaller than y " ) ; 
else System. out. println("y is bigger."); 
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Technical Note: The difference between it conditionals in Java and C or C++ is 
that the test must return a boolean value (true or false). U nlikein C, the test 
cannot return an integer. 



if (engineState == true ) 

System. out. println( "Engine is already on."); 
else { 

System. out. println("Now starting Engine"); 
if (gasLevel >= 1 ) 

engineState = true; 

else System. out. println("Low on gas! Can't start engine."); 

> 

This example uses the test (engineState == false). For boolean tests of this type, a common 
shortcut ismerely to includethefirst part of theexpression, rather than explicitly testing itsvalue 
against true or false: 

if (engineState) 

System. out. println( "Engine is on."); 
else System. out. println( "Engine is off"); 

The Conditional Operator 

An alternative to using the if and else keywords in a conditional statement is to use the 
conditional operator, sometimes called the tanary operator. 

NEW*' A conditional operator is a ternary operator because it has three terms. 

TERM 

The conditional opaatorisan expression, meaning that it returns a value (unlike the more 
genaal if, which can result in any statement or block being executed). Theconditional opaator 
is most useful for very short or simple conditionals, and looks like this: 

test ? trueresult : falseresult 

T he test isan expression that returnstrue or false, just likethetest in theif statement. If the 
test istrue, theconditional opaator returns the value of trueresult] if it's false, it returns the 
valueof faiseresuit. For example, thefollowing conditional teststhevaluesofxand y, returns 
thesmalla of the two, and assigns that value to the variable smaller: 

int smaller = x < y ? x : y; 

Theconditional opaator hasavay low precedence; that is, it’s usually evaluated only afta all 
its subexpressions are evaluated. T he only opaators Iowa in precedence are the assignment 
operators. See the precedence chart in D ay 3’s lesson for a refresha on precedence of all the 
operators. 



switch Conditionals 

A common practicein programming in any language isto test a vari ableagainst some value, and 
if it doesn't match that value, to test it again against a different value, and if it doesn’t match that 
one to make yet another test, and so on. Using only if statements, this can become unwieldy, 
dependingon how it'sformatted and how many different optionsyou haveto test. For example, 
you might end up with a set of it statements something like this or longer: 

if (oper == 1 + " ) 
addargs(arg1 ,arg2) ; 
else if (oper == '=') 
subargs(arg1 ,arg2) ; 
else if (oper == 1 * 1 ) 
multargs(arg1 ,arg2) ; 
else if (oper == 7 ' ) 
divargs(arg1 ,arg2) ; 



Thisform of if statement iscalled a nested if, because each else statement in turn containsyet 
another if, and so on, until all possible tests have been made. 

A common shorthand mechanism for nested ifsthatyou can usein some cases allows you tests 
andactionstogetherinasinglestatement.ThisistheswitchorcaseStatement;inJavait’sswitch 
and behaves as it does in C: 

switch (test) { 
case valueOne: 

resultOne; 

break; 

case valueTwo: 

resultTwo; 

break; 

case valueThree: 

resultThree; 

break; 

default: defaultresult ; 

> 

I n theswitch statement, thetest (a primitive typeof byte, char, short, or int) iscompared with 
each of the case values in turn. If a match is found, the statement, or statements after thetest 
isexecuted. If no match isfound, thedefauit statement is executed. The default isoptional, 
so if there isn’t a match in any of the cases and default doesn’t exist, the switch statement 
completes without doing anything. 

N ote that the significant limitation of theswitch in J ava isthat thetests and values can be only 
simple primitive types (and then only primitive types that arecastableto int). You cannot use 
larger primitive types (long, float) or objects within a switch, nor can you test for any 
relationship other than equality. Thislimitstheusefulnessof switch to all but thesimplest cases; 
nested its can work for any kind of test on any type. 
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H ere's a simple example of a switch statement similar to the nested if shown earlier: 

switch (oper) { 
case : 

addargs(arg1 ,arg2) ; 
break; 



subargs(arg1 ,arg2) ; 
break; 

multargs(arg1 ,arg2) ; 
break; 
case 1 / ' : 

divargs(arg1 ,arg2) ; 
break; 

} 

Note the break statement included in every line. Without the explicit break, once a match is 
made, the statements for that match and also all thestatements further down in theswitch are 
executed until abreak ortheend of theswitch isfound (and then execution continues after the 
end of the switch). In some cases, this may be exactly what you want to do, but in most cases, 
you’ll want to makesuretoindudethebreak so that onlythestatementsyou want to beexecuted 
are executed. 



One handy use of falling through occurs when you want multiple values to execute the same 
statements. In this instance, you can use multiple case lines with no result, and theswitch will 
execute the first statements it finds. For example, in the foil owing switch statement, the string 
"x is an even number. " is printed if x hasvaluesof 2, 4, 6, or 8. All other valuesofx print the 
String “X is an odd number." 



case 6: 
case 8: 

System. out. println("x is an 
break; 

default: System.out.println("x 



even number. " ) ; 
is an odd number. " ) ; 



for Loops 

The tor loop, as in C, repeats a statement or block of statements some number of times until 
acondition ismatched. for loops are frequently used for simple iteration in which you repeat 
ablock of statementsacertain number of times and then stop, butyou can useforloopsforjust 
about any kind of loop. 
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T he for loop in J ava looks roughly like this: 

for ( initialization ; test; increment) { 



statements; 



> 

T he start of the tor loop has three parts: 

□ initialization is an expression that initializes the start of the loop. If you have a loop 
index, this expression might declare and initialize it, for example, mt i = 0 . Variables 
that you declare in this part of the tor loop are local to the loop itself; they cease 
existing after the loop is finished executing. (This is different from C or C++.) 

p test is the test that occurs after each pass of the loop. The test must be a boolean 
expression or function that returns a boolean value, for example, i < 10 . If the test is 
true, the loop executes. Once the test is false, the loop stops executing. 

□ increment is any expression or function call. Commonly, the increment is used to 
change the value of the loop index to bring the state of the loop closer to returning 
false and completing. 

Thestatement part of thetor loop isthestatementthat isexecuted each timetheloop iterates. 
Just as with if, you can include either a single statement here or a block; the previous example 
used a block because that is more common. H ere's an example of a tor loop that initializes all 
the values of a string array to null strings: 

String strArray[] = new String [10]; 
int i; // loop index 

for (i = 0; i < strArray .length; i++) 
strArray[i] = 

Any of the parts of the for loop can be empty statements, that is, you can simply include a 
semicolon with no expression or statement, and that part of thefor loop will be ignored. N ote 
that if you do usea null statement in yourfor loop, you may have to initializeor increment any 
loop variables or loop indices yourself elsewhere in the program. 

You can also have an empty statement for the body of yourfor loop, if everything you want to 
do isin thefirst lineof that loop. For example, here'sonethatfindsthefirst primenumber higher 
than 4000: 

for (i = 4001; notPrime(i); i += 2) 

N otethat a common mistakeinC that also occursin J avaisaccidentally to put asemicolon after 
thefirst lineof thefor loop: 

for (i = 0; i < 10; i++) ; 

System . out . println ( " Loop ! " ) ; 

Because thefirst semicolon endstheloop with an empty statement, theloop doesn't actually do 
anything. T he printm function will be printed only once, because it’s actually outside thefor 
loop entirely. Be careful not to make this mistake in your own Java programs. 
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while and do Loops 

Finally, there arewhiie and do loops, while and do loops, liketor loops, enableablock ofjava 
code to be executed repeatedly until a specific condition is met. W hether you use a tor loop, a 
while, or a do is mostly a matter of your programming style. 

while and do loops, like tor, are exactly the same as those same constructions in C and C++. 

while Loops 

The while loop is used to repeat a statement or block of statements as long as a particular 
condition istrue. while loops look like this: 

while (condition ) { 
bodyOfLoop- 

> 

T h ^condition isa boolean expression. I f it returnstrue, thewhiie loop executes thestatements 
in bodyOfLoop and then tests the condition again, repeating until the condition is false. I’ve 
shown thewhiie loop herewith a block statement, because it’s most commonly used, although 
you can use a single statement in place of the block. 

H ere'san example of awhile loop that copies the elements of an array of integers (in arrayi) 
to anarrayoffioats(in array2), casting each element to a float asit goes. Theonecatch isthat 
if any of theelements in thefirst array iso, theloop will immediately exit at that point. To cover 
both the cases wherein all the elements have been copied and an element is 0, you can use a 
compound test with the && operator: 

while ((ch != 1 ') && (ch != '\t') && (ch != ' \n ' ) && (ch != ’ \r* )) { 
addChar(ch, theName); 
ch = instream. read () ; 

} 

N otethat if thecondition isinitiallyfalsethefirst timeit istested (for example, if thefi rst element 
in that first array iso), the body of thewhiie loop will never be executed. If you need to execute 
the loop at least once, you can do one of two things: 

jtf Duplicate the body of theloop outside thewhiie loop. 

□ U se a do loop (described below). 

The do loop is considered the better solution of the two. 



do. ..while Loops 

The do loop isjust like awhile loop, except that do executes a given statement or block until a 
condition is false. The main difference is that while loops test the condition before looping, 
making it possiblethat the body of the loop will never execute if the condition is false the first 
time it's tested, do loops run the body of the loop at least once before testing the condition, do 
loops look like this: 

do { 

body Of Loop-, 

> while ( condition ); 

H ere, thebodyot Loop part isthestatementsthatareexecuted with each iteration. I t’sshown here 
with a block statement because it’s most commonly used that way, but you can substitute the 
braces for a single statement as you can with the other control-flow constructs. The condition 
isa boolean test. If it returnstrue, theloop isrun again. If it returnstaise, theloop exits. Keep 
in mind that with do loops, the body of the loop executes at least once. 

H ere’s a simple example of a do loop that prints a message each time the loop iterates: 

int x = 1 ; 
do { 

System.out.println( "Looping, round " + x); 

} while’ (x <= 10); 

H ere’s the output of these statements: 

Looping, round 1 
Looping, round 2 
Looping, round 3 
Looping, round 4 
Looping, round 5 
Looping, round 6 
Looping, round 7 
Looping, round 8 
Looping, round 9 
Looping, round 10 

B reaking Out of Loops 

In all theloops(for, while, and do), theloop endswhen the condition you’re testing for is met. 
W hat happensif something odd occurswithinthebody of theloop and you want to exit theloop 
early? For that, you can use the break and continue keywords. 
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You’ve already seen break as part of the switch statement; it stops execution of the switch, and 
the program continues. Thebreak keyword, when used with a loop, does the same thing— it 
immediately halts execution ofthecurrentloop. If you've nested loops within loops, execution 
picks up in the next outer loop; otherwise, the program merely continues executing the next 
statement after the loop. 

For example, suppose you have awhile loop that copies elements from onearray into another. 
Each element in the array should be copied until theend of the array isreached or if an element 
containso. You can test for that latter case insidethe body of thewmie and then usea break to 
exit the loop: 

while (count < arrayl .length) { 
if (arrayl [count] == 0) { 
break; 

} 

array2[count] = arrayl [count] ; 
count++; 

> 

} 

continue issimilarto break exceptthat instead of halting execution of the loop entirely, theloop 
starts over at the next iteration. Fordo and while loops, this means the execution of the clock 
startsover again; fort or loops, theincrement expression devaluated and then block is executed, 
continue is useful when you want to special-case elements within a loop. W ith the previous 
example of copying onearray to another, you can test for whether the current element iso and 
restart theloop if you find it so that theresulting array will never contain zero. N ote that because 
you’re skipping elements in the first array, you now have to keep track of two different array 
counters: 

while (count < arrayl . length) { 
if (arrayl [count] == 0) 
continue; 

array2[count2++] = (float)arrayl [count++] ; 

} 

Labeled Loops 

Both break and continue can have an optional label that tellsjava whereto break to. W ithout 
a label, break jumps outside the nearest loop (to an enclosing loop or to the next statement 
outsidetheloop), and continue restarts the enclosing loop. U sing labeled breaksand continues 
enables you to break outside nested loops or to continue a loop outside the current loop. 
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T o usealabeled loop, add thelabel beforetheinitial part of theloop, with acolon between them. 
T hen, when you use break or continue, add the name of the label after the keyword itself: 

out : 

for (int i = 0; i <10; i++) { 
while (x < 50) { 

if (i * x == 400) 
break out; 



} 

I n thissnippet of code, thelabel out labelstheouterfor loop. Then, insideboththefor and the 
while loop, if a particular condition is met inside both loops, a break causes the execution to 
creak out of both loops and restart back at the label (out). 

H ere’sanother example, thefollowing program containsanested for loop. Insidetheinnermost 
loop, if the sum values of the two counters is greater than four, both loops exit at once: 

foo: 

for (int i = 1; i <= 5; i++) 

for (int j = 1; j <= 3; j++) { 

System. out. printlnC'i is " + i + " , j is " + j ) ; 
if ( (i + j) > 4) 
break foo; 

} 

System.out.println("end of loops"); 

H ere’s the output from this program: 




end of loops 

A ilifdc Asyou can see, theloop iterated until thesum of i and j was greater than 4, andthenboth 
|ftfwiyaq loops exited back to the outer block and the final message was printed. 

Summary 

T oday, you learned about three main topics that you’ll most likely usequite often in your own 
Java programs: arrays, conditionals, and loops. 

You learned how to declare an array variable, create and assign an array object to that variable, 
and access and change elements within that array. 
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C onditionalsindudetheif and switch statements, with which you can branch to different parts 
of your program based on a boolean test. 

Finally, you learned about thetor, while, and do loops, each of which enableyou to executea 
portion of your program repeatedly until a given condition is met. 

N ow that you’ve learned the small stuff, all that’s left isto go over the bigger issues of declaring 
cl asses and creating methodswithin which instancesof those cl asses can communicatewith each 
other by calling methods. Get to bed early tonight, because tomorrow isgoing to beawild ride. 

Q&A 

Q If arrays are objects, and you use new to create them, and they have an instance 
variable length, where is the Array class? I didn't see it in the J ava class libraries. 

A Arrays are implemented kind of weirdly in Java. The Array class is constructed 
automatically when yourj ava program runs; Array provides the basic framework for 
arrays, including the length variable. Additionally, each primitive type and object has 
an implicit subclass of Array that represents an array of that class or object. W hen you 
create a new array object, it may not have an actual class, but it behaves as if it does. 

Q D oesj ava have gotos? 

A TheJ ava language defines the keyword goto, but it is not currently used for anything. 

I n other words, no, J ava does not have gotos. 

Q I declared a variable inside a block statement for an it. W hen the it was done, 
the definition of that variable vanished. Where did it go? 

A I n technical terms, block statements inside braces form a new lexical scope. W hat this 
means is that if you declare a variable inside a block, it’s only visible and usable inside 
that block. Once the block finishes executing, all the variables you declared go away. 
It’s a good idea to declare most of your variables in the outermost block in which 
they’ll be needed— usually at the top of a block statement. The exception might be 
very simple variables, such as index counters in tor loops, where declaring them in the 
first line of thetor loop is an easy shortcut. 

You’ll learn more about variables and scope tomorrow. 

Q W hat can't you use switch with strings? 

A Strings are objects, and switch injava works only for the primitive types that can be 
cast to integers (byte, char, short, and mt). T o compare strings, you have to use 
nested its, which enable more general expression tests, including string comparison. 
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Q 1 t seems to me that a lot of for loops could be written as while loops, and vice 
versa. 

A T rue. T he tor loop is actually a special case of while that enables you to iterate a loop 
a specific number of times. You could just as easily do this with a while and then 
increment a counter inside the loop. Either works equally well. This is mostly just a 
question of programming style and personal choice. 
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In just about every lesson up to this point you’ve been creating Java applications- writing 
classes, creating instance variables and methods, and running those applications to perform 
simple tasks. Also up to this point, you’ve focused either on the very broad (general object- 
oriented theory) or the very minute (arithmetic and other expressions). T oday, you pull it all 
together and learn how and why to create classes by using the following basics: 

□ The parts of a class definition 

Z Declaring and using instance variables 
Z D efining and using methods 

□ Creating Java applications, including the mamo method and howto pass arguments 
to a Java program from a command line 

Defining Classes 

Defining classes is pretty easy; you've seen how to do it a bunch oftimesin previous lessons. To 
define a class, use the class keyword and the name of the class: 

class MyClassName { 



I f this class is a subclass of another class, use extends to i ndicate the superclass of this class: 

class myClassName extends mySuperClassName { 



I f this class implements a specific interface, use implements to refer to that interface: 

class MyRunnableClassName implements Runnable { 



Both extends and implements are optional. You’ll learn about using and defining interfaces in 
Week 3. 

C reating I nstance and C lass Variables 

A class definition with nothing in it is pretty dull; usually, when you create a class, you have 
something you want to add to make that class different from itssu pad asses. Inside each class 
definition are declarations and definitions for variables or methods or both— for the dassand 
for each instance. In this section, you’ll learn all about instance and class variables; the next 
section talks about methods. 
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Defining Instance Variables 

0 n D ay 3, you learned how to declare and initialize local variables- that is, variables inside 
method definitions. I nstance variables, fortunately, aredeclared and defined in exactly the same 
way as local variables; the only difference is their location in the class definition. Instance 
variables are considered instance variables if they are declared outside a method definition. 
C ustomarily, however, most instance variables are defined just after the first line of the class 
definition. For example, Listing 6.1 showsa simpleclassdefinition for thedassBicycie, which 
inherits from the class personpoweredvehicie. This class definition contains four instance 
variables: 

P bikeType: the kind of bicycle this bicycle is- for example, Mountain or street 
in chainGear, the number of gears in the front 

□ rearcogs, the number of minor gears on the rear axle 

□ jsurrentGearFront and currentGearRear: the gears the bike is currently in, both front 
and rear 



Listing 6.1. The bicycle class. 

1: class Bicycle extends PersonPoweredVehicle { 
2: String bikeType; 

3: int chainGear; 

4: int rearCogs; 

5: int currentGearFront; 

6: int currentGearRear; 

7: } 




Constants 

Constants are useful for setting global states in a method or object, or for giving meaningful 
names to object-wide values that will never change. In Java, you can create constants only for 
instance or class variables, not for local variables. 

NEW«~ A constant variable or constant is a variable whose value never changes (which may seem 
TERM strangegiven themeaning of theword "variable”). 

To declare a constant, use the final keyword before the variable declaration and include an 
initial valuefor that variable: 

final float pi = 3.141592; 
final boolean debug = false; 
final int maxsize = 40000; 
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:hnical N ote: T he only way to define constants in J ava is by using the final 
word. Neither theC and C++ constructs for #def me nor const are available in 



C onstants can be u^ Br nami ng various states of an object and then testi ng for those states. | 
Forexample,supposi I haveatest label that can bealigned left, right, orcenter. You can define 

those values as const *^egers: 

final int LEFT = 0; 
final int RIGHT = 1 ; 
final int CENTER = 2 

The variable alignment is then also 

int alignment; 

T hen, later on in the body of a method defii 

this. alignment = CENTER; 

or test for a given alignment: 



u can either set the alignment: 




Class Variables 

As you learned in previous lessons, class variables are global to a class and to all that clas 
instances. You can think of dassvariablesasbeingevenmoreglobal than instancevariables. Class ^ 
variables are good for communicating between different objects with the same class, or for 
keeping track of global states among a set of objects. 

T o declare a class variable, use the static keyword in the class declaration: 



C r eating Methods 

M ethods, asyou learned on D ay 2, definean object’sbehavior- what happenswhen that object 
iscreated and thevariousoperationsthat object can perform during its lifetime. I n this section, 
you’ll get a basic introduction to method definition and how methods work; tomorrow, you’ll 
go into more detail about advanced things you can do with methods. 



Defining Methods 

M ethod definitions have four basic parts: 

□ The name of the method 

□ The type of object or base type this method returns 
jr| A list of parameters 

O T he body of the method 

NEW*~ T he method'ssi gnature is a combination of the name of the method, the type of object or 
TERM base type this method returns, and a list of parameters. 



N ote: T o keep things simple today, I 've left off two optional parts of the method 
definition: an access qualifier such as public or private, and the throws keyword, 
which indicates the exceptions a method can throw. You’ll learn about these parts 
of a method definition in W eek 3. 



In other languages, the name of the method (or function, subroutine, or procedure) is enough 
to distinguish it from other methods in the program. In Java, you can have different methods 
that have the same name but a different return type or argument list. T his is called method 
overloading, and you’ll learn more about it tomorrow. 

H ere’swhat a basic method definition looks like: 

returntype methodname ( typel argl , type2 arg2, type3 arg3..) { 

} 

T he returntype is the primitive type or dassoftheof the value this method returns. Itcan be 
one of the primitive types, a class name, or void if the method does not return avalueat all. 

N otethat if this method returnsan array object, the array brackets can go either after the return 
type or after the parameter list; because the forma way is considerably easia to read, it is used 
in the examples today (and throughout this book): 



int [ ] makeRange (int lower, int upper) {...} 
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The method’s parameter list is a set of variable declarations, separated by commas, inside 
parentheses. These parameters become local variables in the body of the method, whose values 
are the objects or values of primitives passed in when the method is called. 

I nside the body of the method you can have statements, expressions, method calls to other 
objects, conditionals, loops, and soon— everything you’ve I earned about in thepreviouslessons. 

If your method hasareal return typefthat is, it hasnot been declared to return void), somewhere 
insidethe body of the method you need to return a value. Use the return keyword to do this. 
Listing 6.2 shows an exampleof a classthat defines a makeRangeo method. makeRangeo takes 
two integers— a lower bound and an upper bound— and creates an array that contains all the 
integers between those two boundaries (inclusive). 




H ere’s the output of this program: 

a ■ ■ The array: [ 123456789 10] 

output 

Aiip— 



uses a tor loop to print the values of the new array. 





The this Keyword 

Sometimes, in the body of a method definition, you may want to refer to the current object — 
for example, to refer to that object’s instance variables or to pass the current object as an 
argument to another method. T o refer to thecurrent object in these cases, you can usethems 
keyword, this refers to the current object, and you can use it anywhere that object might 
appear— in dot notation to refer to the object’s instance variables, as an argument to a method, 
as the return value for thecurrent method, and so on. H ere’san example: 

t = this.x // the x instance variable for this object 

this.myMethod(this) // call the mymethod method, defined in 
// this class, and pass it the current 
// object 

return this; // return the current object 

I n many cases, however, you may be able to omit the this keyword. You can refer to both 
instance variables and method calls defined in the current class simply by name; the this is 
implicit in those references. So, the first two examples could be written like this: 

t = x // the x instance variable for this object 

myMethod(this) // call the myMethod method, defined in this 
// class 



Note: Omitting the this keyword for instance variables depends on whether there 
are no variables of the same name declared in the local scope. Seethe next section 
for details. 



Keep in mind that because this is a reference to thecurrent instance of a class, it makes sense 
to use it only i nsidethe body of an instance method definition. C lass methods, that is, methods 
declared with the static keyword, cannot use this. 



Variable Scope and Method Definitions 

W hen you refer to avariablewithin your method definitions, J avachecksfor adefinition of that 
variable first in the current scope (which may be a block), then in the outer scopes up to the 
current method definition. If that variable isnot a local variable, J avathen checksfor adefinition 
of that variable as an instance variable in thecurrent class, and then, finally, in each superclass 
in turn. 

Becauseof the wayj ava checksfor the scope of a given variable, it is possiblefor you to create 
a variable in a lower scope such that adefinition of that same variable "hides" theoriginal value 
of that variable. T his can introduce subtle and confusing bugs into your code. 
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For example, note this small Java program: 

class ScopeTest { 
int test = 10; 

void printTest () { 
int test = 20; 

System. out. println("test = " + test); 

} 

> 

I n this class, you have two variables with the same name and definition: the first, an instance 
variable, hasthenametest and is initialized to the value 10. Thesecond isa local variable with 
thesamename, but with thevalue20. Because the local variable hides the instance variable, the 
printino method will print that test is 20. 

You can get around this particular instance by using this, test to refer to the instance variable, 
and just test to refer to the local variable. 

A moreinsidiousexampleofthisoccurswhen you redefine a variable in a subclass that already 
occurs in a superclass. This can create very insidious bugs in your code- for example, you may 
call methods that are intended to change the value of an instance variable, but that change the 
wrong one. Another bug might occur when you cast an object from one class to another— the 
valueof your instance variablemay mysteriously change (because it was getting that valuefrom 
the superclass instead of from your class). The best way to avoid this behavior is to make sure 
that, when you define variables in asubclass, you’re awareof the variables in each of that class’s 
superclasses and you don’t duplicate what is already there. 



Passing Arguments to Methods 

W hen you call a method with object parameters, the variables you pass into the body of the 
method are passed by reference, which meansthat whatever you do to those objects insidethe 
method affects the original objects as well. T his includes arrays and all the objects that arrays 
contain; when you pass an array into a method and modify its contents, the original array is 
affected. (Note that primitive types are passed by value.) 



H ere’s an example to demonstrate how this works. First, you have a simple class definition, 
which includes a single method called on eTozeroo (see Listing 6.3). 



Listing 6.3. The PassByReference class. 

1: class PassByReference { 

2: int OnetoZero (int arg [ ] ) { 

3: int count = 0; 

4: 

5: for (int i = 0; i < arg. length; i++) { 

6: if (arg[l] == 1 ) { 
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count++; 
arg[i] = 0; 



9 

10 

11 

12 

13 



> 

} 

return count; 



Theonetozeroo method does two things: 

□ ft counts the number of ones in the array and returns that value. 
IP If it finds a one, it substitutes a zero in its place in the array. 



Listing 6.4 showsthemain ( ) method for thePassByRef erence class, which teStStheonetoZero( ) 
method: 




H ere is the output of this program: 

Values of the array: [1345117] 

Number of Ones = 3 

New values of the array: [0345007] 

Let’s go over the maino method line by line so that you can see what is going on. 

Lines2 through 4 set up theinitial variablesfor thisexample. T hefirst oneisan array of integers; 
the second oneisan instance of the class passByRef erence, which isstored in the variable test. 
The third is a simple integer to hold the number of ones in the array. 
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Lines6 through 11 print out the initial values of the array; you can see the output of these lines 
in the first line of the output. 

Linel2 iswherethereal worktakesplace; thisiswhereyou call theonetozero( > method, defined 
in the object test, and pass it the array stored in am. This method returnsthe number of ones 
in the array, which you’ll then assign to the variable numones. 

Got it so far? Line 13 prints out the number of ones, that is, the value you got back from the 
onetozeroo method. It returns three, as you would expect. 

Thelast bunch of linesprint out thearray values. Becau sea ref erencetothearray object ispassed 
to the method, changing the array inside that method changes that original copy of thearray. 
Printing out the values in lines 14 through 18 proves this- that last line of output shows that 
all the i s in the array have been changed to os. 

Class Methods 

Just as you have class and instance variables, you also have class and instance methods, and the 
difference between thetwotypesofmethodsare analogous Cl ass methods are global to thedass 
itself and availableto anyother cl assesor objects Therefore, class methodscan beused anywhere 
regardless of whether an instance of the class exists or not. 

For example, thej ava class libraries include a class called Math. T he Math class defines a whole 
set of math operations that can be used in any program with the various number types: 

float root = Math.sqrt (453.0) ; 

System. out. print( "The larger of x and y is" + Math .max(x,y) ) ; 

To define class methods, use the static keyword in front of the method definition, just as you 
would createadass variable. For example, that max cl assmethod might haveasignaturelikethis: 

static int max (int argl , int arg2) { ... > 

I n a similar example, Java supplies "wrapper” classes for each of the base types- for example, 
classes for integer, Float, and Boolean. Using class methods defined in those classes, you can 
convert to and from objects and base types. For example, theparseinto class method in the 
integer dasstakesa string and a radix (base) and returns the value of that string as an integer: 

int count = Integer. parselnt("42“ , 10) // returns 42 

M ost methods that operate on a particular object, or that affect that object, should be defined 
as instance methods. M ethods that provide some general utility but do not directly affect an 
instance of that class are better declared as class methods. 



C reating J ava Applications 

N ow that you know how tocreatedasses, objects, and class and instance variables and methods, 
all that’s left isto put it together into something that can actually run-in other words, to create 
aj ava application. 

Applications, to refresh your memory, arejava programs that run on their own. Applications 
aredifferentfrom applets, which requireH otJavaoraJava-capablebrowsertoviewthem.M uch 
of whatyou’ve been using upto thispoint havebeen J ava applications; next week you’ll diveinto 
how to create applets. (Applets require a bit more background in order to get them to interact 
with the browser and draw and update with the graphics system. You’ll learn all of this next 
week.) 

A Java application consists of one of more classes and can be as large or as small as you want it 
to be. H otjava is an example of a Java application. The only thing you need to make a Java 
application run is one class that serves as the "jumping-off” point for the rest of your Java 
program. I f your program is small enough, it may need only the one class. 

T hejumping-off dassfor your program needsonething: amain < > method. W hen you run your 
compiled J ava class (using the J ava interpreter), the main ( ) method is the first thing that gets 
called. N oneof thisshould bemuch of a surprise to you at thispoint; you’ve been creatingjava 
applications with maino methods all along. 

The signature for the main o method always looks like this: 

public static void main (String arg[]) (...} 

H ere’s a run-down of the parts of the maino method: 

□ public means that this method is available to other classes and objects. The maino 
method must be declared public. You’ll learn more about public and private 
methods in Week 3. 

□ static means that this is a class method. 

□ void means the maino method doesn't return anything. 

□ main ( ) takes one parameter: an array of strings. T his argument is used for command- 
line arguments, which you’ll learn about in the next section. 

The body of the maino method contains any code you need to get your application started: 
initial variables or creating instances of any classes you may have declared. 

When Java executes the maino method, keep in mind that maino is a class method- the class 
that holdsitisnot automatically instantiated when your program runs. If you want to treat that 
class as an object, you have to instantiate it in the maino method yourself (all theexamplesup 
to this point have done this). 
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Java Applications and Command-Line 
Arguments 

BecauseJ ava applications are stand-alone programs, it’s useful to be able to pass arguments or 
options to that program to determine how the program is going to run, or to enable a generic 
program to operate on many different kinds of input. Command-line arguments can be used 
for many different purposes- for example, to turn on debugging input, to indicate a filename 
to read or write from, or for any other information that you might want your J ava program to 
know. 

Passing Arguments to Java Programs 

T o pass arguments to aj ava program, you merely append them to the command line when you 
run your Java program: 

java Myprogram argumentOne 2 three 

0 n thiscommand line, you havethree arguments: argumentone, thenumber 2 , and three. N ote 
that a space separates arguments, so thiscommand line produces three arguments: 

java myprogram Java is cool 

T 0 group arguments, surround them with double-quotes. Thiscommand line produces one 
argument: 

java myprogram "Java is cool" 

T he double-quotes are stripped off before the argument gets to your J ava program. 

Handling Arguments in Your Java Program 

H ow does Java handle arguments? It stores them in an array of strings, which is passed to the 
maino method in your Java program. Remember the signature for mamo: 

public static void main (String arg [ ] ) {...} 

H ere, arg isthe name of the array of stringsthat containsthelist of arguments. You can actually 
call it anything you want; argv iscommon (after the array of the same name from C and Unix 
shell scripting). 

Inside your mamo method, you can then handle the arguments your program was given by 
iterating over the array of arguments and handling those arguments any way you want. For 
example, Listing 6.5 is a really simple class that prints out the arguments it gets, one per line. 
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Listing 6.5. The EchoArgs class. 



Type 



Is class EchoArgs { 

2: public static void main(String args[]) { 

3: for (int i = 0; i < args. length; i++) { 

4: System. out. println ("Argument " + i + " : " + args[i]); 

5: } 

6: } 

7: } 



T he following is some sample input and output from this program: 



java EchoArgs 1 2 3 jump 

Argument 0: 1 
Argument 1 : 2 
Argument 2: 3 
Argument 3: jump 

java EchoArgs "too bar" zap twaddle 5 





Argument 0: too bar 
Argument 1 : zap 
Argument 2: twaddle 
Argument 3: 5 



N otehow the arguments are grouped in the listing; putting quotes around too bar causes that 
argument to be treated as one unit inside the argument array. 



Technical Note: The array of arguments in Java is not analogous to argv in C and 
Unix. In particular, arg[ 0 ], the first element in the array of arguments, is the first 
command-line argument after the name of the class- not the name of the program 
as it would bein C. Becareful ofthisasyou write your Java programs. 



An important thing to note about the arguments you pass into a J ava program is that those 
argumentswill be stored inan array of strings. T his meansthat any arguments you passtoyour 
Java program will be converted to strings so they can be stored in the argument array. T o treat 
them as non-strings, you’ll have to convert them to whatever type you want them to be. 




For example, suppose you have a very simplejava program called sumAverage that takes any 
number of numeric arguments and returnsthesum and theaverageof those arguments. Listing 
6.6 shows a first pass at this program. 
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Listing 6.6. First try at the SumAverage class. 

1 : class SumAverage { 

2: public static void main (String args[]) { 

3: int sum = 0; 

4: 

5: for (int i = 0; i < args. length; i++) { 

6: sum += args[i] ; 

7: > 




9 
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System. out. println("Sum is: “ + sum); 
System. out. printing "Average is: " + 
(float)sum / (float)args. length) ; 



Atfirstglance,thisprogramseemsratherstraightforward— atorloopiteratesoverthearray 
pS of arguments, summing them, and then thesum and the average are printed out asthelast 
step. 

What happens when you try and compile this? You get the following error: 

SumAverage. java: 9: Incompatible type for +=. Can't convert java. lang. String to int. 
sum += args[i] ; 

You get this error because the argument array is an array of strings. Even though you passed 
integers into the program from the command line, those integers were converted to strings 
before they were stored in the array. To be able to sum those integers, you have to convert them 
back from strings to integers. There’sadass method for themteger class, called parseint,that 
does just this. If you change line 7 to use that method, everything works just fine: 



sum += Integer. parselnt(args[i] ) ; 

N ow, compiling the program produces no errorsand running it with variousarguments returns 
the expected results. For example, java SumAverage i 2 3 returns the following output: 




Summary 

T oday,you put together everythingyou’vecomeacrossintheprecedingdaysofthisweek about 
how to create J ava classes and use them in Java applications. This included the following: 

Z Instance and class variables, which hold the attributes of the class and its instances. 

You learned how to declare them, how they are different from regular local variables, 
and how to declare constants. 
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0i Instance and class methods, which define a class’s behavior. You learned how to define 
methods, including the parts of a method's signature, how to return values from a 
method, how arguments are passed in and out of methods, and the this keyword to 
refer to the current object 

□ Java applications— all about the main o method and how it works as well as how to 
pass arguments into a Java application from a command line. 

Q&A 

Q I tried creating a constant variable inside a method, and I got a compiler error 
when I tried it. What was I doing wrong? 

A You can create only constant (final) class or instance variables; local variables cannot 
be constant. 

Q static and final are not exactly the most descriptive words for creating class 
variables, class methods, and constants. Why not use class and const? 

A static comesfrom Java’s C++ heritage; C++ uses the static keyword to retain 
memory for class variables and methods (and, in fact, they aren’t called class methods 
and variables in C ++: static member functions and variables are more common 
terms). 

final, however, is new. final is used in a more general way for classes and methods to 
indicate that those things cannot be subclassed or overridden. Usingthefinai 
keyword for variables is consistent with that behavior, final variables are not quite the 
same as constant variables in C++, which iswhy the const keyword isnot used. 

Q I n my class, I have an instance variable called name. I also have a local variable 
called name in a method, which, because of variable scope, gets hidden by the 
local variable. Is there any way to get hold of the instance variable's value? 

A The easiest way isnot to name your local variables the same names as your instance 
variables. If you feel you must, you can use this, name to refer to the instance variable 
and name to refer to the local variable. 

Q I want to pass command-line arguments to an applet. H ow do I do this? 

A You’re writing applets already? Been skipping ahead, have you? The answer is that you 
useHTM L attributes to pass arguments to an applet, not the command line (you 
don’t have a command line for applets). You’ll learn how to do this next week. 

Q I wrote a program to take four arguments, but if I give it too few arguments, it 
crashes with a run-time error. 

A T esting for the number and type of arguments your program expects is up to you in 
your Java program; Java won’t do it for you. If your program requires four arguments, 
test that you have indeed been given four arguments, and return an error message if 
you haven't. 
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M ethodsarearguablythemost important part of any object-oriented language. Whereasdasses 
and objects provide the framework, and class and instance variables provide a way of holding 
that class or object’s attributes and state, it is the methods that actually provide an object's 
behavior and define how that object interacts with other objects in the system. 

Yesterday, you learned a littleabout defining methods. W ith what you learned yesterday, you 
could create lots of Java programs, but you'd be missing some of the features of methods that 
make them really powerful, that make your objects and classes more efficient and easier to 
understand. Today, you’ll learn about these additional features, including the following: 

□ Overloading methods, sometimes called creating polymorphic methods- that is, 
creating methods with multiple signatures and definitions but with the same name 

□ Creating constructor methods- methods that enableyou to initialize objects to set up 
an initial state in the system when an object is created 

□ Overriding methods— creating a different definition for a method that has been 
defined in a superclass 

□ Finalizer methods— a way for an object to clean up after itself before it is removed 
from the system 

Creating Methods with the Same 
Name, Different Arguments 

Yesterday, you learned how to create methods with a single name and a single signature. 
M ethods in J ava can also be overloaded— that is, you can create methods that have the same 
name, but different signatures and different definitions. M ethod overloading enables instances 
of your class to havea simpler interface to other objects (no need for entirely different methods 
that do essentially thesame thing) and to behavedifferently based on the input to that method. 

When you call a method in an object, Java matches up the method name and the number and 
type of arguments to choose which method definition to execute. 

T o createan overloaded method, all you need to do iscreateseveral different method definitions 
in your cl ass, all with thesamename, but with different parameter lists(either in number ortype 
of arguments) and with different bodies. J ava can understand method overloading as long as 
each parameter list is unique for each method name. 

N otethat J avadifferentiatesoverloaded methodswith thesamename, based on thenumber and 
typeofparametersto that method, not on itsreturn type. That is, if you try to createtwo methods 
with thesamename, same parameter list, but different return types, you’ll get a compiler error. 
T hevariablenamesyou chooseforeach parameter to the method are irrelevant— all that matters 
is the number and the type. 



H ere'san example of creating an overloaded method. Listing 7.1 showsasimpleclassdefinition 
for a class called MyRect, which defines a rectangular shape. The MyRect class has four instance 
variables to define the upper left and lower right corners of the rectangle: xi, yi, x2, and y2. 



N ote: W hy did I call it MyRect? J ava’s awt package has a class called Rectangle that 
implements much of this same behavior. I called this class MyRect to prevent 
confusion between the two classes. 



Type 



Listing 7.1. The MyRect class. 



class MyRect { 
int xi = 0 
int yi = 0 
int x2 = 0 
int y2 = 0 



W hen anew instanceof themyRect cl assisinitially created, all itsinstancevariablesareinitialized 
to 0. Let’s define a buucmecto method that takes four integer arguments and "resizes” the 
rectangle to have the appropriate values for its corners, returning the resulting rectangle object 
(note that because the arguments have the same names as the instance variables, you have to 
make sure to use this to refer to them): 

MyRect buildRect(int xi , int yi , int x2, int y2) { 
this.xl = xi ; 
this.yl = yi ; 
this.x2 = x2; 
this.y2 = y2; 
return this; 

> 

W hat if you want to define a rectangle’s dimensions in a different way— for example, by using 
point objects rather than individual coordinates? You can overload buiidRecto so that its 
parameter list takes two point objects (note that you’ll need to import the point class at thetop 
of your source file so Java can find it): 

MyRect buildRect(Point topLeft, Point bottomRight) { 
xi = topLeft. x; 
yi = topLeft. y; 
x2 = bottomRight. x; 
y2 = bottomRight .y; 
return this; 
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Perhaps you want to definethe rectangle using atop corner and a width and height. Just create 
a different definition for buiidRecto: 

MyRect buildRect(Point topLeft, int w, int h) { 
xl = topLeft. x; 
yl = topLeft. y; 
x2 = (xl + w) ; 
y2 = (yl + h); 
return this; 

> 

T o finish up this example, let's create a method to print out the rectangle’s coordinates, and a 
maino method to test it all (just to prove that this does indeed work). Listing 7.2 shows the 
completed class definition with all its methods. 



Listing 7.2. The complete MyRect class. 

import java.awt. Point; 

class MyRect { 
int xl = 0; 
int yl = 0; 
int x2 = 0; 
int y2 = 0; 

MyRect buildRect (int xl , int yl , int x2, int y2) { 
this.xl = xl ; 
this.yl = yl ; 
this.x2 = x2; 
this.y2 = y2; 
return this; 



MyRect buildRect (Point topLeft, Point bottomRight) { 
xl = topLeft. x; 
yl = topLeft. y; 
x2 = bottomRight. x; 
y2 = bottomRight. y; 
return this; 



MyRect buildRect (Point topLeft, int w, int h) { 
xl = topLeft. x; 
yl = topLeft. y; 
x2 = (xl + w) ; 
y2 = (yl + h); 
return this; 



void printRect(){ 

System. out. print ("MyRect: <" + xl + ", “ + yl ) ; 
System.out.println(" , " + x2 + ", " + y2 + ">"); 




> 
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public static void main (String args[]) { 

MyRect rect = new MyRect(); 

System. out. println ("Calling buildRect with coordinates 25,25 50,50:"); 
rect.buildRect(25, 25, 50, 50); 
rect.printRect() ; 

System, out .println ( " " ) ; 

System. out. println ("Calling buildRect w/points (10,10), (20,20):"); 
rect. buildRect (new Point(10,10) , new Point (20,20) ) ; 
rect.printRect() ; 

System . out . println ( " " ) ; 

System. out. print( "Calling buildRect w/1 point (10,10),"); 

System. out. println(" width (50) and height (50)”); 

rect. buildRect (new Point(10,10) , 50, 50); 
rect.printRect() ; 

System, out .println ( " " ) ; 



H ere's the output of thisj ava program: 

Calling buildRect with coordinates 25,25 50,50: 
MyRect: <25, 25, 50, 50> 



Calling buildRect w/points (10,10), (20,20): 
MyRect: <10, 10, 20, 20> 



Calling buildRect w/1 point (10,10), width (50) and height (50) 

MyRect: <10, 10, 60, 60> 

Asyou can see from thisexample, all the buildRect o methods work based on the arguments 
with which they are called. You can defineasmany versionsof a method asyou need to in your 
own classes to implement the behavior you need for that class. 

Constructor Methods 

I n addition to regular methods, you can also defineconstructor methodsin your classdefinition. 

NEW** A constructor method isaspecial kind of method that determineshow an object isinitialized 
TERM when it’s created. 

U nlike regular methods, you can’t call a constructor method by calling it directly; instead, 
constructor methods are called byj ava automatically. H ere’s how it works: when you use new 
to create a new instance of a class, J ava does three things: 

□ Allocates memory for the object 
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□ Initializes that object’s instance variables, either to their initial values or to a default (0 
for numbers, nuii for objects, false for booleans) 

□ Calls the class’s constructor method (which may be one of several methods) 

Ifadassdoesn'thaveany special constructor methodsdefined, you’ll still end up with an object, 
but you’ll have to set its instance variables or call other methodsthat object needsto initialize 
itself to that object afterward. All theexamplesyou'vecreated up to this point have behaved like 
this. 

By defining constructor methods in your own classes, you can set initial values of instance 
variables, call methods based on those variables or call methods on other objects, or calculate 
initial properties of your object. You can also overload constructors, as you would regular 
methods, to create an object that has specific properties based on theargumentsyou give to new. 



Basic Constructors 

Constructors look a lot like regular methods, with two basic differences: 

Z C onstructors always have the same name as the class. 

Z C onstructors don’t have a return type. 

For example, Listing 7.3 shows a simple class called person, with a constructor that initializes 
its instance variables based on the arguments to new. The class also includes a method for the 
object to introduce itself, and a main 0 method to test each of these things. 



Listing 7.3. The Person class. 

class Person { 

String name; 
int age; 

Person(String n, int a) { 




void printPerson() { 

System. out. print("Hi, my name is " + name); 
System.out.println(" . I am " + age + " years old."); 

> 

public static void main (String args[]) { 

Person p; 

p = new Person( "Laura" , 20); 
p.printPerson() ; 

System . out . println ( " " ) ; 
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p = new Person( "Tommy" , 3); 
p.printPerson() ; 

System. out. println( " 



H ere's the output for this example program: 



pup 



Hi, my name is Laura. I am 20 years old. 
Hi, my name is Tommy. I am 3 years old. 



Calling Another Constructor 

Someconstructorsyouwritemaybeasuperset of another constructor defined in your cl ass; that 
is, they might have the same behavior plus a little bit more. Rather than duplicating identical 
behavior in multi pleconstructormethodsin your class, it makes sense to beableto just call that 
first constructor from inside the body of thesecond constructor. J ava provides a special syntax 
for doing this. T o call a constructor defined on the current class, use this form: 

this(arg1, arg2, arg3...); 

The arguments to this are, of course, the arguments to the constructor. 



Overloading Constructors 

Like regular methods, constructors can also take varying numbers and types of parameters, 
enabling you to create your objects with exactly the properties you want it to have, or for it to 
beableto calculate properties from different kinds of input. 

For example, thebuiidRecto methodsyou defined in theiuiyRectdassearliertoday would make 
excellent constructors, becausewhat they'redoing isinitializing an object'sinstancevariablesto 
theappropriateobjects. So, instead of theoriginal buiidRecto method you had defined (which 
took four parameters for the coordinates of the corners), you can create a constructor instead. 
Listing 7.4 shows a new class, called MyRect 2 , that has all the same functionality of the original 
MyRect, except with overloaded constructor methods instead of thebuiidRecto method. 



Listing 7.4. The MyRect2 class (with constructors). 



import j ava. awt. Point; 



class MyRect2 { 
int xl = 0; 
int yl = 0; 



continues 
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Listing 7.4. continued 

int y2 = 0; 

MyRect2(int xl , int yl , int x2, int y2) { 
this .xl = xl ; 
this.yl = yl ; 
this.x2 = x2; 
this.y2 = y2; 



MyRect2(Point topLeft, Point bottomRight) { 
xl = topLeft. x; 
yl = topLeft. y; 
x2 = bottomRight. x; 
y2 = bottomRight.y; 



MyRect2(Point topLeft, int w, int h) { 
xl = topLeft. x; 
yl = topLeft. y; 

y2 = (yl + h) ; 



void printRect()( 

System. out. print ("MyRect: <" + xl + ", " + yl ) ; 
System. out .println( " , " + x2 + ", " + y2 + ">"); 



public static void main (String args[]) { 

MyRect2 rect; 

System. out. println( "Calling MyRect2 with coordinates 25,25 50,50:"); 
rect = new MyRect2(25, 25, 50,50); 
rect.printRect() ; 

System . out . println ( " " ) ; 

System. out. println ("Calling buildRect w/points (10,10), (20,20):"); 
rect= new MyRect2(new Point(10,10) , new Point(20,20) ) ; 
rect.printRect() ; 

System . out . println ( " " ) ; 

System. out. print ( "Calling buildRect w/1 point (10,10),"); 

System. out. println(" width (50) and height (50)"); 
rect = new MyRect2(new Point(10, 10) , 50, 50); 
rect.printRect() ; 

System . out . println ( " " ) ; 



H ere’s the output for this example program (it’s the same output from the previous example; 
only the code to produce it has changed): 



Output 



Calling MyRect2 with coordinates 25,25 50,50: 
MyRect: <25, 25, 50, 50> 



Calling buildRect w/points (10,10), (20,20): 
MyRect: <10, 10, 20, 20> 



Calling buildRect w/1 point (10,10), width (50) and height (50) 
MyRect: <10, 10, 60, 60> 



Overriding Methods 

W hen you dassa method in an object, J avalooksforthat method definition in thecorrect object, 
and if it doesn't find one, it passes the method call up the class hierarchy until a method 
definition isfound. M ethod inheritance enables you to define and use methods repeatedly in 
subclasses without having to duplicate the code itself. 

H owever, theremay betimeswhen you want an object to respond to thesamemethodsbut have 
different behavior when that method is called. In this case, you can override that method. 
Overriding a method involves defining a method in a subclass that has the same signature as a 
method in a superclass. Then, when that method is called, the method in thesubdass isfound 
and executed instead of the one in the superclass. 



Creating Methods 

that Override Existing Methods 

T o override a method, all you have to do is create a method in yoursuperclassthat hasthesame 
signature (name, return type, and parameter list) as a method defined by one of your class's 
superclasses. Because Java executes the first method definition it finds that matches the 
signature, this effectively "hides” the original method definition. H ere’s a simple example; 
Listing 7.5 shows a simple class with a method called printMeo, which prints out the name of 
the class and the values of its instance variables. 



Listing 7.5. The Printciass class. 

class PrintClass { 
int x = 0; 
int y = 1 ; 




void printMe() { 

System. out. println( "X is " + x + " , Y is " + y) ; 
System. out. println(“I am an instance of the class " + 
this.getClass() .getName() ) ; 
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Listing 7.6 shows a class called printsubciass that is a subclass of (extends) printciass. T he 
only differencebetweenprintciass and printsubciassisthatthelatterhasaz instance variable. 



Type 



Listing 7.6. The Printsubciass class. 



class PrintSubClass extends PrintClass { 
int z = 3; 



public static void main (String args[]) { 
PrintSubClass obj = new PrintSubClass ( ) ; 
obj .printMe() ; 



H ere’s the output from Printsubciass: 

Output 



| ■ In the main o method of printsubciass, you create a printsubciass object and call the 
prmtMeo method. N otethat printsubciass doesn't definethismethod, sojava looks for 
it in each of printsubciass’s superclasses- and finds it, in this case, in printciass. 
Unfortunately, because printMeo isstill defined in printciass, it doesn’t print the z instance 
variable. 



N ow, let’s create a third class. pnntsubciass2 is nearly identical to printsubciass, but you 
override the prmtMeo method to indudethez variable. Listing 7.7 shows this class. 



Type 



Listing 7.7. The PrintSubCiass2 class. 



class PrintSubClass2 extends Printciass { 
int z = 3; 



public static void main (String args[]) { 

PrintSubClass2 obj = new PrintSubClass2( ) ; 
obj .printMe() ; 



N ow, when you instantiate this class and call the prmtMeo method, the version of prmtMeo 
you defined for thisdassiscalled instead of theonein thesuperdassprintciass (asyou can see 
in this output): 





x is 0, y is 1 , z is 3 

I am an instance of the class PrintSubClass2 



Calling the Original Method 

U sually, there are two reasons why you want to override a method that a superclass has already 
implemented: 

□ To replace the definition of that original method completely 

□ To augment the original method with additional behavior 

You'vealready learned about thefirst one; by overriding a method and giving that method anew 
definition, you’ve hidden the original method definition. But sometimes you mayjust want to 
add behaviorto theoriginal definition rather than erase it altogether. This is particularly useful 
where you end up duplicating behavior in both the original method and the method that 
overridesit; by being ableto call theoriginal method inthebodyoftheoverridden method, you 
can add only what you need. 

T o call theoriginal method from insidea method definition, usethesuper keyword to pass the 
method call up the hierarchy: 

void myMethod (String a, String b) { 

// do stuff here 
super. myMethod(a, b); 

// maybe do more stuff here 

> 

The super keyword, like thethis keyword, is a placeholder for this class’s superclass. You can 
use it anywhere you want to refer to your superclass rather than to the current class. 



For example, Listing 7.8 shows those printMe o methods used in the previous example. 



Type 



Listing 7.8. The printMe methods. 



// from PrintClass 
void printMe () { 

System. out. println("X is " + x + " , Y is " + y) ; 
System. out. println("I am an instance of the class" + 
this.getClass( ) .getName( ) ) ; 



//from PrintSubClass2 
void printMe () { 

System. out. println("X is " + x + ", Y is " + y + ", Z is " + z); 
System. out. println(“I am an instance of the class " + 
this.getClass( ) .getName( ) ) ; 
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Rather than duplicating most of the behavior of the superclass's method in thesubclass, you can 
rearrange the superclass’s method so that additional behavior can easily be added: 

// from PrintClass 
void printMe() { 

System. out. println("I am an instance of the class" + 
this . getClass ( ) . getName ( ) ) ; 

System. out. println("X is " + x); 

System. out. println("Y is " + y); 



T hen, in the superclass, when you overrideprintMe, you can merely call theoriginal method and 
then add the extra stuff: 

// From PrintSubClass2 
void printMe() { 
super. printMe() ; 

System. out. println("Z is " + z); 

} 

> 

H ere’s the output of calling printMeo on an instance of the superclass: 

I am an instance of the class PrintSubClass2 
Y 

Z is 3 

Overriding Constructors 

Constructorscannot technically be overridden. Because they always have thesamenameas the 
current class, you're always creating new constructorsinstead of inheriting the onesyou’ve got. 
M uch of the time, thisisfine, because when your class’s constructor is called, the constructor 
with the same signature for all your superclass is also called, so initialization of all the parts of 
a class you inherit can happen. 

H owever, when you’re defining constructors for your own class, you may want to change how 
your object is initialized, not only by initializing the information your class adds, but also to 
change the information that is already there. You can do this by explicitly calling your 
superclass's constructors. 

To call a regular method in a superclass, you usesuper.methodname(arguments). Because with 
constructors you don’t havea method name to call, however, you have to usea different form: 



super(arg1, arg2, ...); 

Similar to using this(...) in a constructor, super)...) calls the constructor method for the 
immediate superclass (which may, in turn, call the constructor of its superclass, and so on). 




For example, Listing 7.9 shows a class called NamedPoint, which extends the class point from 
J ava’sawt package. T hepomt dasshasonly one constructor, which takesan x and a y argument 
and returnsapoint object. NamedPoint has an additional instance variable(astringforthename) 
and defines a constructor to initialize x, y, and the name. 



Type 



Listing 7.9. The NamedPoint class. 



1: import java.awt. Point; 



2: class NamedPoint extends Point { 

3: String name; 

4: 

5: NamedPoint (int x, int y, String name) { 

6: super(x,y); 

7: this. name = name; 

8: } 

9: } 



. j ■ The constructor defined here for NamedPoint (lines 6 through 8) callspoint’sconstructor 
Analysis method to initialize point’s instance variables (x and y). Although you can just as easily 
initializex and y yourself, you may not know what other thingspomt isdoing to initialize 
itself, so it’s always a good idea to pass constructors up the hierarchy to make sure everything 
is set up correctly. 

Finalizer Methods 

Finalizer methods are like theoppositeof constructor methods; whereas a constructor method 
is used to initialize an object, finalizer methods are called just before the object is garbage- 
collected and its memory reclaimed. 

T o create a finalizer method, include a method with the following signature in your class 
definition: 

void finalize () { 



I nside the body of that finaiizeo method, include any cleaning up you want to do for that 
object. 

Before you start using finalizer methods extensively in yourjava programs, however, be aware 
that finalizer methodshave several very important restrictions. First of all, thefinalizer method 
isnot guaranteed to becalled until theobject’smemory isactually reclaimed, which may besome 
time after you’ve removed all references to that object. 




More About Methods 



You can alwayscall thetinaiizeo method yourself at any time; it'sjust a plain method likeany 
other. H owever, calling finalize o does not trigger an object to be garbage-collected. Only 
removing all referencesto an object will cause it to be marked for deleting, and even then, Java 
may or may not call thet inaiize ( > method itself— regardlessof whether or not you’ve already 
called it. 

Finalizer methods are best used for optimizing the removal of an object— for example, by 
removing referencesto other objects, by cleaning up thingsthat object may havetouched, orfor 
other optional behaviors that may make it easier for that object to be removed. I n most cases, 
you may not need to usetinaiizeo at all. 

Summary 

T oday, you learned all kindsof techniquesfor using, reusing, defining, and redefining methods. 
You learned how to overload a method name so that the same method can have different 
behaviors based on the arguments with which it’s called. You learned about constructor 
methods, which areused to initializeanew object when it’s created. You learned about method 
inheritance and how to overridemethodsthathavebeen defined in a cl ass’s superclasses. Finally, 
you learned about finalizer methods, that can beused to clean up after an object just beforethat 
object is garbage-collected and its memory reclaimed. 

C ongratulations on completing your fi rst week of T each Yourself J ava i n 21 D ays! Starti ng next 
week, you’ll apply everything you’ve learned this week to writing Java applets and to working 
with more advanced conceptsin putting together J ava programsand working with thestandard 
Java class libraries. 

Q&A 

Q I created two methods with the following signatures; 

int total(int argl , int arg2, int arg3) {...} 
float total(int argl, int arg2, int arg3) {...} 

Thejava compiler complains when I try to compile the class with these method 
definitions. But their signatures are different- what have I done wrong? 

A M ethod overloading in Java works only if the parameter lists are different— either in 
number or type of arguments. Return type is not relevant for method overloading. 
Think about it— if you had two methods with exactly the same parameter list, how 
would J ava know which one to call? 



Q You described using thethiso method (thisorg, arg, ...)) to call a construc- 
tor from inside another constructor. Are you limited to using thethiso method 
call inside constructors? 

A N o, you can use that method anywhere to refer to the current object’s constructor. 

On an existing object, calling a constructor is an easy way to reinitialize that object 
back to its default state (or to change it to have the state that you want it to have). 

Q Can I overload overridden methods (that is, can I create methods that have the 
same name as an inherited method, but a different parameter list)? 

A Sure! As long as a parameter lists vary, it doesn't matter whether you've defined a new 
method name or one that you’ve inherited from a superclass. 

Q I created a finalizer method to decrement a class variable and print a message 
when my object gets garbage-collected. This way I can keep track of how many 
objects of this class are running at any given time. But sometimes finalize o gets 
called and sometimes it doesn't. How can I guarantee that finalize o will be 
called and my program will operate correctly? 

A finalize o is provided as a convenience, to give an object a chance to clean up after 
itself, finalize o may or may not be called on any given object before it is garbage- 
collected, so you should not depend on its existence; you should be using finalize q 
only to provide program optimizations. 

If you absolutely require that an object perform some operation before that object gets 
garbage-collected, you should create a specific method other than finalize o and 
explicitly call that method before discarding references to that object. 
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Java Applet Basics 



M uch of Java’s current popularity has come about because of Java-capable World Wide Web 
browsers and their support for applets: small programs that run inside a Web page and can be 
used to create dynamic, interactive Web designs. Applets, as I noted at the beginning of this 
book, are written in thejava language, and can be viewed in any browser that supportsjava, 
including Sun’s H otj ava an d N etscape'sN avi gator 2.0. Learning how to create applets is most 
likely the reason you bought this book, so let’s waste no more time. 

Last week, you focused on learningaboutthej avalanguageitself, andmostofthelittleprograms 
you created werej ava applications. This week, now that you have the basics down, you move 
on to creating and using applets, which includes a discussion of many of the classes in the 
standard J ava class library. 

T oday, you’ll start with the basics: 

□ A small review of differences between J ava applets and applications 

□ Getting started with applets: the basics of how an applet works and how to create your 
own simple applets 

□ Including an applet on aWeb page by using the <applet> tag, including the various 
features of that tag 

Z Passing parameters to applets 

H ow Applets and Applications Are 
D ifferent 

Although you explored the differences between Java applications and Java applets in the early 
part of this book, let’s review them. 

I n short, J ava applications arestand-alonej ava programsthat can be run by using just thej ava 
interpreter, for example, from a command line. M ost everything you’ve used up to this point 
in the book has been aj ava application, albeit a simple one. 

Java applets, however, are run from insideaW orld W ideW eb browser. A referenced an applet 
is embedded in a Web page using a special HTML tag. When a reader, using a Java-aware 
browser, loadsa W eb page with an applet in it, the browser downloadsthat applet from a W eb 
server and executes it on the local system (the one the browser is running on). 

BecauseJ ava applets run insidethej ava browser, they have access to the same capabilities that 
thebrowser has: sophisticated graphics, drawing, and image processing packages; user interface 
elements; networking; and event handling. J ava applications can also take advantage of these 
features, but theydon’t requirethem (you’ll learn how to createj ava applicationsthat use applet- 
like graphics and U I features on Day 14). 




T h e ad van tages ap p I ets h ave over ap p I i cati o n s i n term s of grap h i cs an d U I capabilities, however, 
are hampered by restrictions on what applets can do. G iven the fact that J ava applets can be 
downloaded from anywhere and run on a client’s system, restrictions are necessary to prevent 
an applet from causing system damageor security breaches. Without these restrictions in place, 
Java applets could be written to contain viruses or trojan horses (programs that seem friendly 
butdosomesortofdamageto thesystem), or beused to compromise thesecurity of the system 
that runs them. The restrictions on what an applet can do include the following: 

n Applets can’t read or write to the reader’s file system, except in specific directories 
(which are defined by the user through an access control list that, by default, is 
empty). Some browsers may not even allow an applet to read or write to the file 
system at all. 

□ Applets can’t usually communicate with a server other than the one that had originally 
stored the applet. (T his may be configurable by the browser; however, you should not 
depend on having this behavior available.) 

n Applets can’t run any programs on the reader's system. For Unix systems, this includes 
forking a process. 

n Applets can’t load programs native to the local platform, including shared libraries 
such as DLLs. 

I n addition, J ava itself includes various forms of security and consistency checking in thej ava 
compiler and interpreters prevent unorthodoxuseofthelanguage(you’ll learn moreaboutthis 
on D ay 21). T his combination of restrictions and security features make it more difficult for a 
roguej ava applet to do damage to the client’s system. 



N ote: T he most important words in the last sentence are "more difficult.’’ T hese 
restrictions can prevent most of the more obvious ways of trying to cause damage 
to a client’s system, but it's impossibleto be absolutely sure that a clever program- 
mer cannot somehow work around those restrictions. Sun has asked the N et at 
large to try to break J ava’s security and to create an applet that can work around the 
restrictions imposed on it. If a hole is found, Sun will patch it. You’ll learn about 
more issues in Java security on Day 21. 



Creating Applets 

For the most part, all the Java programs you’ve created up to this point have been Java 
applications- simple programs with a single maino method that created objects, set instance 
variables, and ran methods. T oday and in the days following, you’ll be creating applets 
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exclusively, so you should have a good grasp of how an applet works, the sorts of features an 
applet has, and whereto start when you first create your own applets. W ithout further ado, let’s 
get on with it. 

T o create an applet, you create a subclass of the class Applet, in the java.applet package. The 
Applet class provides behavior to enable your applet not only to work within the browser itself, 
but also to take ad vantage of the capabilities of AWT to includeU I elements, to handlemouse 
and keyword events, and to draw to thescreen. Although your applet can haveasmany "helper" 
cl asses as it needs, it’sthe main applet class that triggers theexecution of theapplet. That initial 
applet class always has a signature like this: 

public class myClass extends java. applet. Applet { 



Notethepubiic keyword. Javarequiresthat your applet subclass bedeclared public. Again, this 
istrueonly of your main applet class; any helper classes you create can bepubiic or private as 
you wish. Public, private, and other forms of access control are described on Day 15. 

When Java encounters your applet in a Web page, it loads your initial applet class over the 
network, aswell as any other helper classesthat first class uses. U nlikewith applications, where 
J avacallsthemain < > method directly on your initial class, when your applet isloaded,J avacreates 
an in stance of that cl ass, and all the system -based methods are sent to that instance. Different 
applets on the same page, or on different pages that use the same class, use different instances, 
so each one can behave differently from other applets running on the same system. 

Major Applet Activities 

T o create a basic Java application, your class has to have one method, marno, with a specific 
signature. Then, when your application starts up, main is executed, and from main you can set 
up the behavior that your programs need. Applets are similar but more complicated. Applets 
have many different activities that correspond to various major events in the life cycle of the 
applet- for example, initialization, painting, ormouseevents. Each activity hasacorresponding 
method, so when an event occurs, the browser or other J ava-capable tool calls those specific 
methods. 

By default, none of those activity methods have any definitions; to provide behavior for those 
events you must overridethe appropriate method in your applet's subclass. You don’t have to 
override all of them, of course; different applet behavior requires different methods to be 
overridden. 

You’ll learn about the various important methods to override as the week progresses, but, fora 
general overview, here are five of the more important methods in an applet's execution: 
initialization, starting, stopping, destroying, and painting. 
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public void destroyO { 
> 



Technical Note: H ow is destroyO different from finalize*), which was described 
on Day 7? First, destroy*) applies only to applets, finalize o is a more general- 
purpose way for a single object of any type to clean up after itself. 

T he other difference is that destroy* ) is always called when the applet has finished 
executing, either because the browser is exiting or because the applet is being 
reloaded, finalize*) is not guaranteed to be executed. 



Painting 

Painting is how an applet actually draws something on the screen, be it text, a line, a colored 
background, or an image. Painting can occur many hundreds of times during an applet’s life 
cycle- for example, once after the applet isinitialized, if the browser is placed behind another 
window on the screen and then brought forward again, if the browser window is moved to a 
different position on thescreen, or perhaps repeatedly in the case of animations. You override 
the paint*) method for your applet to have an actual appearance on thescreen. The paint*) 
method looks I ike this: 

public void paint (Graphics g) { 



N otethat unliketheother major methodsin thissection, paint * ) takesan argument, an instance 
of thedassGraphics. T hisobject iscreated and passed to paint by thebrowser, so you don’t have 
to worry about it. H owever, you will have to make sure that the Graphics class (part of the 
java.awt package) getsimported into your applet code, usually through an import statement at 
the top of your Java file: 

import java.awt. Graphics; 

A Simple Applet 

On Day 2, you created a si m pie applet called H elloAgai nApplet (this was the one with the big 
red Heiio Again). T here, you created and used that applet as an exampleof creating a subclass. 
Let’sgo over the code for that applet again, thisti me looking at it slightly differently in light of 
the things you just learned about applets. Listing 8.1 shows the code for that applet. 




Listing 8.1. The Hello Again applet. 



Listing 



2: import java.awt.Font; 

3: import java.awt. Color; 



import java.awt. Graphics; 
import java.awt.Font; 
import java.awt. Color; 



5: public class HelloAgainApplet extends java. applet. Applet { 



6: 

7: Font f = new Font ( "TimesRoman" , Font . BOLD, 36) ; 



8 



9 

10 

11 

12 



public void paint (Graphics g) { 
g.setFont(f ) ; 
g .setColor (Color. red) ; 
g.drawString( "Hello again!' 1 , 5, 50); 



13 



14 



■ Thisappletoverridespainto,oneofthemajormethodsdescribed intheprevioussection. 
|fSS Because the applet doesn’t actually execute (all it does is print a couple of words to the 
screen), and there’s not really anything to initialize, you don’t need a start o orastopo 
or an intto method. 

Thepaint method is where the real work of thisapplet (what little work goes on) really occurs. 
The Graphics object passed into the paint o method holds that graphics state- that is, the 
current features of the drawing surface. LineslOand 11 set up thedefault font and colorforthis 
graphics state (here, the font object help in thet instance variable, and an object representing 
the color red that’s stored in the color class’s variable red). 

Linel2thendrawsthestring "Heiio Again!" by usi ng thecurrent font and color at the position 
5, 50. N otethattheo point for y is at the top left of theapplet’sdrawing surface, with positive 
y moving downward, so 50 is actually at the bottom of the applet. Figure 8.1 shows how the 
applet's bounding box and the string are drawn on the page. 




Figure 8.1. 

D rawing the applet. 
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I ncluding an Applet on a Web Page 

After you create a class or classes that contain your applet and compilethem into class files as 
you would any other J ava program, you have to createa W eb page that will hold that applet by 
using the HTM L language. There is a special HTML tag for including applets in Web pages; 
Java-capablebrowsersusetheinformation contained in that tag to locatethecompiled class files 
and execute theapplet itself. I n thissection, you’ll learn about how to putj ava appletsin a W eb 
page and how to serve those files to the W eb at large. 



Note: The following section assumes you have at least a passing understanding of 
writing HTM L pages. If you need help in this area, you may find the book Teach 
Yourself Web Publishing with HTM L in 14 Days useful. It is also from Sams.Net 
(and also written by one of the authors of this book). 



The <APPLET>Tag 

T o include an applet on a Web page, usethe<APPLET> tag. <applet> is a special extension to 
HTML for including appletsin Webpages. Listing 8.2 shows a very simple example of a Web 
page with an applet included in it. 



Listing 8.2. A simple HTML page. 

1 : <HTML> 

2: <HEAD> 

3: <TITLE>This page has an applet on it</TITLE> 

4: </HEAD> 

5 : <BODY> 

6: <P>My second Java applet says: 

7: <BR> 

8: <APPLET CODE="HelloAgainApplet . Class" WIDTH=200 HEIGHT=50> 

9: There would be an applet here if your browser 

10: supported Java. 

11: </APPLET> 

12: </BODY> 

13: </HTML> 




Analysis 



There are three things to note about the <applet> tag in this page: 



□ ThecoDE attribute indicates the name of the class file that loads this applet, including 
the .class extension. In this case, the class file must be in the same directory as this 
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HTML file. T o indicate applets are in a different directory, use codebase, described 
later today. 

□ width and height are required and used to indicate the bounding box of the applet— 
that is, how big a box to draw for the applet on the Web page. Be sure you set width 
and height to bean appropriate size for the applet; depending on the browser, if your 
applet draws outside the boundaries of the space you’ve given it, you may not be able 
to see or get to those parts of the applet outside the bounding box. 

Hi The text between the <applet> and </applet> tags is displayed by browsers that do 
not understand the <applet> tag (which includes most browsers that are not Java- 
capable). Because your page may be viewed in many different kinds of browsers, it is a 
very good idea to include alternate text here so that readers of your page who don’t 
havejavawill see something other than a blank line. H ere, you include a simple 
Statement that says There would be an applet here if your browser supported 
Java. 

N otethat the<APPLET> tag, like the <img> tag, is not itself a paragraph, so it should be enclosed 
inside a more general text tag, such as<p> or one of the heading tags (<hi> , <H2>, and so on). 



Testing the Result 

N ow with a class file and an HTM L file that refers to your applet, you should be able to load 
that HTML file into your Java-capable browser (using either the 0 pen Local... dialog item or 
afileU RL,orbyindicatingthefilenameonacommandline).Thebrowserloadsand parsesyour 
HTML file, and then loads and executes your applet class. 

Figure 8.2 shows theH ello Again applet, in case you’ve forgotten what it lookslike. 



Figure 8.2. 

T he H ello Again applet. 



Hello again! 



Making J ava Applets Available to the Web 

After you have an applet and an HTM L file, and you’ve verified that everything is working 
correctly on your local system, the last step is making that applet available to the W orld W ide 
W eb at large so that anyone with a J ava-capable browser can view that applet. 
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J ava applets are served by a W eb server the same way that H T M L fi les, i mages, and other medi a 
are. You don’t need special server software to make] ava applets avail able to theW eb; you don’t 
even need to configure your server to handlej ava files. If you have a Web server up and running, 
orspaceon a Web server availableto you, all you have to do ismoveyourH TM L and compiled 
class files to that server, as you would any other file. 

I f you don’t havea W eb server, you have to rent spaceon oneor set one up yourself. (W eb server 
setup and administration, as well as other facetsof W eb publishing in general, are outside the 
scope of this book.) 



More About the <APPLET>Tag 

In its simplest form, by using code, width, and height, the <applet> tag merely creates a space 
of the appropriate size and then loads and plays the applet in that space. T he <applet> tag, 
however, does include several attributes that can help you better integrate your applet into the 
overall design of your W eb page. 



N ote: T he attributes available for the <applet> tag are almost identical to those for 
theHTM L <img> tag. 



ALIGN 

TheALiGN attribute defines how theapplet will be aligned on the page. This attribute can have 
one of nine values: left, right, top, texttop, middle, absmiddle, baseline, bottom, and 

ABSBOTTOM. 

I n thecaseof align=left and align=right, theapplet isplaced at theleft or right marginsof the 
page, respectively, and all text following that applet flows in the space to the right or left of that 
applet. The text will continue to flow in that space until the end of theapplet, or you can use 
a line break tag (<br>) with the clear attribute to start theleft line of text below that applet. T he 
clear attribute can have one of three values: clear=left starts the text at the next clear left 
margin, cLEAR=RiGHTdoesthesamefor the right margin, and cLEAR=ALLStartsthetext at thenext 
line where both margins are clear. 

For example, here's a snippet of HTM L code that aligns an applet against the left margin, has 
sometext flowing alongside it, and then breaks at the end of the paragraph so that the next bit 
of text starts below the applet: 
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<P><APPLET CODE="HelloAgainApplet" WIDTH=300 HEIGHT=200 
ALIGN=LEFT>HellO Again ! </APPLET> 

To the left of this paragraph is an applet. It's a 
simple, unassuming applet, in which a small string is 
printed in red type, set in 36 point Times bold. 

<BR CLEAR=ALL> 

<P>In the next part of the page, we demonstrate how 
under certain conditions, styrofoam peanuts can be 
used as a healthy snack. 

Figure 8.3 shows how this applet and the text surrounding it might appear in a Java-capable 
browser. 



Figure 8.3. 

An applet aligned left. 




For smaller applets, you may want to indudeyour applet within asinglelineof text. To do this, 
there are seven valuesfor align that determinehow theapplet isvertically aligned with thetext: 

□ align=textttop aligns the top of the applet with the top of the tallest text in the line. 
.!□ align=top aligns the applet with the topmost item in the line (which may be another 

applet, or an image, or the top of thetext). 

I align=absiviiddle aligns the middle of the applet with the middle of the largest item in 
the line. 

O align=middle aligns the middle of the applet with the middle of the baseline of the 
text. 

□ align=baseline aligns the bottom of theapplet with the baseline of thetext. 
align=baseline is the same as align=bottom, but align=baseline is a more descri ptive 
name. 

□ align=absbottom aligns the bottom of theapplet with thelowest item in theline 
(which may be the baseline of thetext or another applet or image). 

Figure 8.4 shows the various alignment options, where the line is an image and the arrow isa 
small applet. 
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Figure 8.5. 

Vertical and horizontal 
space. 




CODE andCODEBASE 

code is used to indicate the name of the class file that holds the current applet. IfcoDE is used 
alonein the <applet> tag, the cl ass file is searched forin thesamedi rectory as the HTM L file 
that references it. 

If you want to store your class files in a different directory than that of your HTM L files, you 
have to tell thejava-capablebrowser whereto find those class files. To do this, you usecoDEBASE. 
code contains only the name of the class file; codebase contains an alternate pathname where 
classesarecontained. For example, ifyou storeyourdassfilesin adirectory cal led /classes, which 
isin the same directory as your HTM L files, codebase is the following: 

<APPLET CODE="myclass. class" CODEBASE="classes" 

WIDTH=1 00 HEIGHT=1 00> 

Passing Parameters to Applets 

W ith J ava applications, you can pass parametersto your main < ) routi ne by using arguments on 
the command line. You can then parse those arguments inside the body of your class, and the 
application acts accordingly based on the arguments it is given. 

Applets, however, don’t haveacommand line. H ow do you passin different arguments to an 
applet? Applets can get different input from the H TM L file that contains the <applet> tag 
through the use of applet parameters. To set up and handle parameters in an applet, you need 
two things: 

□ A special parameter tag in the H T M L file 

□ Code in your applet to parse those parameters 
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Applet parameters come in two parts: a name, which is simply a name you pick, and a value, 
which determines the value of that particular parameter. So, for example, you can indicate the 
color of text in an applet by using a parameter with the namecoior and the value red. You can 
determine an animation’s speed using a parameter with the name speed and the value 5. 

I n the H T M L fie that contains the embedded applet, you indicate each parameter using the 
<param> tag, which has two attributes for the name and the value, called (surprisingly enough), 
name and value. T he <param> tag goes inside the opening and closing <applet> tags: 

<APPLET CODE="MyApplet. Class" WIDTH=100 HEIGHT=100> 

< PAR AM NAME=f ont VALUE="TimesRoman "> 

<PARAM NAME=size VALUE="36"> 

A Java applet appears here.</APPLET> 

ThisparticularexampledefinestwoparameterstotheM yApplet applet: one whosenameistont 
and whose value is TimesRoman, and one whose name is size and whose value is 36. 

T hose parameters are passed to your applet when it is loaded. In theimto method for your 
applet, you can then get hold of those parameters by using the getparameter method, 
getparameter takes one argument- a string representing the name of the parameter you’re 
looking for— and returnsa string containing the corresponding value of that parameter. (Like 
arguments in J ava applications, all the parameter values are converted to strings.) To get the 
value of the font parameter from theHTM L file, you might have a line such as this in your 
inito method: 

String theFontName = getParameter("font") ; 






N ote: T he names of the parameters as specified in <param> and the names of the 
parameters in getparameter must match identically, including having the same 
upper and lowercase. In other words, <param= NAME="name"> is different from 
<param NAME="Name">. If your parameters are not being properly passed to your 
applet, make sure the parameter names match. 



N ote that if a parameter you expect has not been specified in the HTML file, getparameter 
returns null. M ost often, you will want to test for a nun parameter and supply a reasonable 
default: 

if (theFontName == null) 
theFontName = "Courier" 

Keep in mind also that becausegetParameter returnsstrings, if you want a parameter to besome 
other object or type, you haveto convert it yourself. T 0 parsethesize parameter from that same 
HTM Lfileand assign it to an integervariablecalledthesize,you might usethefollowing lines: 



int theSize; 

String s = getParameter( "size" ) ; 
if (s == null) 
theSize = 12; 

else theSize = Integer. parselnt(s) ; 

G et it? N ot yet? Let’s create an exampleof an applet that usesthistechnique. You’ll modify the 
H elloAgainApplet so that it says hello to a specific name, for example "Heiio Bin- or "Heiio 
Mice \ The name is passed into the applet through an HTM L parameter. 

Let's start with the original HeiioAgainAppiet class: 

import java.awt. Graphics; 
import java.awt. Font; 
import java.awt. Color; 

public class MoreHelloApplet extends java. applet. Applet { 

Font f = new Font("TimesRoman", Font. BOLD, 36) ; 

public void paint (Graphics g) { 
g.setFont(f ) ; 
g . setColor (Color . red) ; 
g .drawString( "Hello Again !“ , 5, 50); 

} 

> 

T hefi rstthingyou needtoaddinthisdassisaplaceforthename. Becauseyou’ll need that name 
throughout the applet, let'sadd an instance variablefor the name, just after the variablefor the 
font: 

String name; 

T o set a valuefor the name, you have to get the parameter. T he best place to handle parameters 
to an applet is inside an mito method. Theinito method is defined similarly to painto 
(public, with no arguments, and areturn typeofvoid). M akesurewhen you test for a parameter 
that you test for a valueof nun. Thedefault, inthiscase, ifanameisn’tindicated, isto say hello 
to "Laura": 

public void init() { 
this. name = getParameter( "name" ) ; 
if (this. name == null) 
this. name = "Laura"; 

} 

Onelastthingtodonow that you havethenamefromtheHTM L parameters isto modify the 
name so that it’s a complete string— that is, to tack "Heiio " onto the beginning, and an 
exclamation point onto theend. You could dothisin thepamt method just before printing the 
string to the screen. H ere it’s done only once, however, whereas in paint it’s done every time 
the screen is repainted— in other words, it'sslightly moreefficient to doit insidemito instead: 



this. I 



"Hello " + this. name 





Java Applet Basics 



And now, all that’s left is to modify the paint o method. The original drawstring method 
looked likethis: 



g .drawString( "Hello Again! “ , 5, 50); 

T o draw the new string you have stored in the name instance variable, all you need to do is 
substitute that variable for the literal string: 



g.drawString(this.name, 5, 50); 



Listing 8.3 showsthefinal result of thewioreHeiioAppiet class. Compileitso that you haveadass 
file ready. 



Type 



Listing 8.3. The MoreHeiioAppiet class. 



import java.awt. Graphics; 
import java.awt. Font; 
import java.awt. Color; 

public class MoreHeiioAppiet extends java. applet. Applet { 

Font f = new Font ( "TimesRoman" , Font .BOLD, 36) ; 

String name; 

public void init() { 

this. name = getParameterj "name" ) ; 
if (this. name == null) 
this. name = "Laura"; 
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this. name = "Hello " + this. name + "!"; 



public void paint(Graphics g) { 
g.setFont(f) ; 
g.setColor(Color.red) ; 
g.drawString(this.name, 5, 50); 



Now, let’screatetheHTM L file that contains this applet. Listing 8.4 shows a new Web page 
for the M oreH elloApplet applet. 



Listing 8.4. The HTML file for the MoreHeiioAppiet applet. 

1 : <HTML> 

2: <HEAD> 

3: <TITLE>HellO ! </TITLE> 

4: </HEAD> 

5 : <BODY> 
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6: <P> 

7: <APPLET CODE= l, MoreHelloApplet .Class" WIDTH=300 HEIGHT=50> 

8: < PAR AM NAME=name VALUE="Bonzo"> 

9: Hello to whoever you are! 

10: </APPLET> 

11: </B0DY> 

12: </HTML> 



N ote the <applet> tag, which points to the class file for the applet with the appropriate 
width and height (300 and 50). Just below it (line 8 ) isthe<PARAM> tag, which you use to 
pass in the name. H ere, the name parameter is simply name, and the value is the strong 

Loading up thisHTM L file produces the result shown in Figure 8.6. 

Figure 8.6. 

The result of 

M oreH elloApplet, first try. 



Hello Bonzo! 




Let’s try a second example. Remember that in the code for M oreH elloApplet, if no name is 
specified, thedefault isthename "Laura". Listing 8.5 creates an HTML file with no parameter 
tag for name. 

Tuna Listing 8.5. Another HTML File for the 
lype MoreH elloApplet applet. 

1 : <HTML> 

2: <HEAD> 

3: <TITLE>HellO ! </TITLE> 

4: </HEAD> 

5: <BODY> 

6: <P> 

7: <APPLET CODE="MoreHelloApplet .Class" WIDTH=300 HEIGHT=50> 

8: Hello to whoever you are! 

9: </APPLET> 

10: </BODY> 

11: </HTML> 



H ere,becausenonamewassupplied,theappletusesthedefault, and theresultiswhatyou might 
expect (see Figure 8.7). 
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Figure 8.7. 

The result of 



M oreH elloApplet, 
second try. 



Hello Laura! 



Summary 



Applets are probably the most common use of the Java language today. Applets are more 
complicated than manyj avaapplicationsbecausethey areexecuted and drawn inlinewith aW eb 
page. Applets can more easily provide easy access to the graphics, user interface, and events 
systems in the W eb browser itself. T oday, you learned the basics of creating applets, including 
the following things: 

Z All applets you develop using J ava inherit from the Applet class, part of the java.applet 
package. TheAppiet class provides basic behavior for how the applet will be integrated 
with and react to the browser and various forms of input from that browser and the 
person running it. By subclassing Applet, you have access to all that behavior. 

Z Applets have five main methods, which are used for the basic activities an applet 
performs during itslife cycle: mito, starto, stopo, destroyo, and painto. 
Although you don't need to override all these methods, these are the most common 
methodsyou’ll see repeated in many of the applets you’ll createin thisbook and in 
other sample programs. 

jfj to run a compiled applet class file, you include it in an HTM L Web page by using 
the <applet> tag. W hen a J ava-capable browser comes across <applet>, it loads and 
plays the applet described in that tag. N otethat to publish Java applets on the World 
Wide Web alongside HTM L files you do not need special server software; any plain 
old W eb server will do just fine. 

□ Unlike applications, applets do not have a common line on which to pass arguments, 
so those arguments must be passed into the applet through the HTM L file that 
contains it. You indicate parameters in an HTM L file by using the <param> tag inside 
the opening and closing <applet> tags. <param> has two attributes: name for the name 
of the parameter, and value for its value. I nside the body of your applet (usually in 
mito), you can then gain access to those parameters using thegetparameter method. 
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Q&A 

Q I n the first part of today's lesson, you say that applets are downloaded from 
random Web servers and run on the client's system. What's to stop an applet 
developer from creating an applet that deletes all the files on that system, or in 
some other way compromises the security of the system? 

A Recall that Java applets have several restrictionsthat make it difficult for most of the 
more obvious malicious behavior to take place. For example, becausej ava applets 
cannot read or write files on the client system, they cannot delete files or read system 
files that might contain private information. Because they cannot run programs on the 
client’s system, they cannot, for example, use the system’s mail system to mail files to 
someone elsewhere on the network. 

I n addition, J ava’s very architecture makes it difficult to circumvent these restrictions. 
The language itself, thej ava compiler, and thej ava interpreter all have checks to make 
sure that no one has tried to sneak in bogus code or play games with the system itself. 
You’ll learn more about these checks at the end of this book. 

Of course, no system can claim to be entirely secure, and the fact that Java applets are 
run on the client’s system makes them especially ripe for suspicion. 

Q Wait a minute. If I can't read or write files or run programs on the system the 
applet is running on, doesn't that mean I basically can't do anything other than 
simple animations and flashy graphics? H ow can I save state in an applet? H ow 
can I create, say, a word processor or a spreadsheet as a Java applet? 

A For everyone who doesn't believe that Java is secure enough, there is someone who 
believes that Java’s security restrictions are too severe for just these reasons. Yes, Java 
applets are limited because of the security restrictions. But given the possibility for 
abuse, I believe that it’s better to err on the side of being more conservative as far as 
security is concerned. Consider it a challenge. 

Keep in mind, also, that Java applications have none of the restrictions that Java 
applets do, but because they are also compiled to bytecode, they are portable across 
platforms. It may be that the thing you want to create would make a much better 
application than an applet. 

Q I have an older version of H otj ava. I followed all the examples in this section, 
but H otjava cannot read my applets (it seems to ignore that they exist). What's 
going on? 
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A You most likely have an alpha version of H otj ava. Recall that significant changes were 
made to thej ava API and how Java applets are written between alpha and beta. The 
results of these changes are that browsers that support alpha applets cannot read beta 
applets, and vice versa. TheHTM L tags are even different, so an older browser just 
skips over newer applets, and vice versa. 

By the time you read this, there may be a new version of H otj ava with support for 
beta. If not, you can useN etscape2.0 or theJDK’s applet viewer to view applets 
written to the beta specification. 

Q I noticed in a page about the <applet> tag that there's also a name attribute. You 
didn't discuss it here. 

A name is used when you have multiple applets on a page that need to communicate with 
each other. You’ll learn about this on Day 12. 

Q I have an applet that takes parameters and an H TM L file that passes it those 
parameters. But when my applet runs, all I get are null values. What's going on 
here? 

A D o the names of your parameters (in the name attribute) match exactly with the names 
you're testing for in g etParameter?They must be exact, including case, for the match 
to be made. M ake sure also that your <param> tags are inside the opening and closing 
<applet> tags, and that you haven't misspelled anything. 




Graphics, Fonts, 
and Color 



by Laura Lemay 




Graphics, Fonts, and Color 



N ow you havea basic understanding of how appletswork. Forthe remainder of thisweek you’ll 
cover the sorts of things you can do with applets with the built-in Java class libraries, and how 
you can combinethem to produce interesting effects. You'll start today with how todrawto the 
screen— that is, how to produce lines and shapes with the built-in graphics primitive, how to 
print text using fonts, and how to use and modify color in your applets. T oday you’ll learn, 
specifically: 

□ H ow the graphics system works in Java: the Graphics class, the coordinate system used 
to draw to the screen, and how applets paint and repaint 

□ U sing thejava graphics primitives, including drawing and filling lines, rectangles, 
ovals, and arcs 

(3 Creating and using fonts, including how to draw characters and strings and how to 
find out the metrics of a given font for better layout 

Z All about color in Java, including the color class and how to set the foreground 
(drawing) and background color for your applet 



N ote: T oday’s lesson discusses many of the basic operations available to you with 
thej ava class libraries regarding graphics, fonts, and color. H owever, today’s lesson, 
as well as all of thisbook, is also intended to be more of an introduction and an 
overview than an exhaustive description of all the features available to you. Be sure 
to check out the J ava API documentation for more information on the classes 
described today. 



T he G raphics C lass 

W ithj ava’sgraphics capabilities, you can draw lines, shapes, characters, and imagesto thescreen 
insideyour applet. M ostofthegraphicsoperationsinJavaaremethodsdefinedintheGraphics 
class. You don't haveto createaninstanceofGraphicsinordertodrawsomethinginyourapplet; 
in your applet’s paint o method (which you learned about yesterday), you aregiven aGraphics 
object. By drawing on that object, you draw onto your applet and the results appear on screen. 

TheGraphics cl assispart of thejava.awt package, so if yourapplet does any painting(asit usually 
will), makesureyou import that class at the beginning of yourj ava file: 

import j ava. awt. Graphics; 

public class MyClass extended java. applet. Applet { 
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The Graphics Coordinate System 

T o draw an object on thescreen, you call oneof thedrawing methodsavailablein theGraphics 
class. All the drawing methods have arguments representing endpoints, corners, or starting 
locations of the object as values i n the applet’s coordi nate system— for example, aline starts at 
the poi nts 1 0 , 1 0 and ends at the poi nts 20,20. 

Java’s coordi nate system hastheorigin (0,0) in thetop left corner. Positive x values are to the 
right, and positivey valuesaredown. All pixel valuesareintegers; thereareno partial orfractional 
pixels. Figure 9.1 shows how you might draw a simple square by using this coordinate system. 



Figure 9.1. 

Thejava graphics coordi- 
nate system. 
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Java’s coordinate system is different from many painting and layout programs that have their 
x and y in the bottom left. If you’renot used to working with thisupside-down graphics system, 
it may take some practice to get familiar with it. 



Drawing and Filling 

T he Graphics class provides a set of simple built-in graphics primitives for drawing, including 
lines, rectangles, polygons, ovals, and arcs. 




Note: Bitmap images, such asGIF files, can also be drawn by using the Graphics 
class. You’ll learn about this tomorrow. 
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Lines 



T o draw straight lines, usethedrawLine method, drawnne takes four arguments: the x and y 
coordinates of the starting point and the x and y coordinates of the ending point. 

public void paint (Graphics g) { 
g.drawLine(25,25,75,75) ; 

> 

Figure 9.2 shows the result of this snippet of code. 



T hej ava graphics primitives provide not just one, but three kinds of rectangles: 

Z Plain rectangles 

□ Rounded rectangles, which are rectangles with rounded corners 
Z T hree-dimensional rectangles, which are drawn with a shaded border 

Foreachoftheserectangles, you have two methodstochoosefrom: onethat draws therectangle 
in outline form, and onethat draws the rectangle filled with color. 

T o draw a plain rectangle, use either the drawRect or miRect methods. Both take four 
arguments: the x and y coordinates of the top left corner of the rectangle, and the width and 
height of the rectangleto draw. For example, thefollowing paint < ) method drawstwo squares: 
the left one is an outline and the right oneisfilled (Figure 9.3 shows the result): 

public void paint (Graphics g) { 
g.drawRect(20,20,60,60) ; 
g . f illRect (120,20,60,60) ; 



Rounded rectanglesare,asyou might expect, rectangleswith rounded edges. ThedrawRoundRect 
and t iiiRoundRect methodsto draw rounded rectangles are similar to regular rectangles except 
that rounded rectangles have two extra arguments for the width and height of the angle of the 



Figure 9.2. 

Drawinglines 




Rectangles 
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corners. Those two argumentsdeterminehow far along theedgesof the rectanglethearc for the 
corner will start; the first for the angle along the horizontal plane, the second for the vertical. 
Larger valuesfor the angle width and height make the overall rectangle more rounded; values 
equal to the width and height of the rectangle itself produce a circle. Figure 9.4 shows some 
examples of rounded corners. 



Figure 9.3. 

Rectangles 



Figure 9.4. 

Rounded corners 
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H ere’sa paint method that draws two rounded rectangles: one as an outline with a rounded 
corner 10 pixelssquare; theother, filled, with arounded corner 20 pixelssquare(F igure9.5 shows 
the resulting squares): 

public void paint (Graphics g) { 

g.drawRoundRect (20,20,60,60,10, 10) ; 
g . fillRoundRect (120, 20,60 ,60,20,20); 

> 
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Figure 9.5. 

Rounded rectangles 




Finally, therearethree-dimensional rectangles. T hese rectan gl es aren 't really 3D ; instead, they 
have a shadow effect that makes them appear either raised or indented from the surface of the 
applet. Three-dimensional rectangles have four arguments for the x and y of the start position 
and the width and height of the rectangle. The fifth argument isa boolean indicating whether 
the 3D effect is to raise the rectangle (true) or indent it (false). As with the other rectangles, 
therearealso different methodsfordrawing and filling: draw3DRect and t m3DRect. H ere'scode 
toproducetwoofthem— theleft oneindented, therightoneraised (F igure9.6 showstheresult): 

public void paint (Graphics g) { 

g.draw3DRect(20,20,60,60,true) ; 
g . draw3DRect ( 1 20 , 20 , 60 , 60 , f alse ) ; 



Figure 9.6. 

Three-dimensional 

rectangles 



Note: In the current beta version of thejava developer's kit, it is very difficult to 
see the 3D effect on 3D rectangles, due to a very small line width. (In fact, I 
enhanced Figure 9.6 to better show the effect.) If you are having troubles with 3D 
rectangles, this may be why. D rawing 3D rectangles in any color other than black 
makes them easier to see. 
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Polygons 

Polygons are shapes with an unlimited number of sides. T o draw a polygon, you need a set of 
x and y coordinates, and thedrawing method then starts at one, drawsalinetothesecond, then 
a line to the third, and soon. 

Aswith rectangles, you can draw an outlineorafilled polygon (thedrawPoiygon and t mpoiygon 
methods, respectively). You also have a choice of how you want to indicate the list of 
coordinates- either as arrays of x and y coordinates or as an instance of the polygon class. 

Using the first method, thedrawPoiygon and finpoiygon methods take three arguments: 

|3 An array of integers representing x coordinates 

□ An array of integers representing y coordinates 

□ An integer for the total number of points 

T hex and y arrays should, of course, have the same number of elements. 

H ere'san exampleof drawing a polygon’s outline by using this method (Figure 9.7 shows the 
result): 

public void paint (Graphics g) { 

int exes[ ] = { 39,94,97,142,53,58,26 }; 
int whys[ ] = { 33,74,36,70,108,80,106 >; 
int pts = exes. length; 

g.drawPolygon(exes,whys,pts) ; 



Figure 9.7. 

A polygon. 




N otethatjava does not automatically dosethe polygon; if you want to complete theshape, you 
have to includethestarting point of thepolygon attheend ofthearray. D rawingafilled polygon, 
however, joins the starting and ending points. 
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Thesecond way of CallingdrawPolygon and fillPolygon isto usea Polygon object. The Polygon 
classisuseful if you intend to add points to thepolygon or if you’re building thepolygon on the 
fly. T he polygon class enables you to treat the polygon as an object rather than havi ng to deal 
with individual arrays. 

T o create a polygon object you can either create an empty polygon: 

Polygon poly = new Polygon(); 

or create a polygon from a set of points using integer arrays, as in the previous example: 

int exes[ ] = { 39,94,97,142,53,58,26 >; 
int whys [ ] = { 33,74,36,70,108,80,106 }; 
int pts = exes. length; 

Polygon poly = new Polygon(exes, whys, pts) ; 

Once you have a polygon object, you can append points to thepolygon as you need to: 

poly.addPoint(20,35) ; 

Then, to draw the polygon, just use the polygon object as an argument to drawPoiygon or 
fiiipoiygon. H ere’sthatpreviousexample, rewritten thistimewithapoiygon object. You’ll also 
fill this polygon rather than just drawing its outline (Figure 9.8 shows the output): 

public void paint (Graphics g) { 

int exes[ ] = { 39,94,97,142,53,58,26 }; 
int whys [ ] = { 33,74,36,70,108,80,106 }; 
int pts = exes. length; 

Polygon poly = new Polygon(exes, whys, pts) ; 
g.fillPolygon(poly) ; 



Figure 9.8. 

Another polygon. 




Ovals 

Useovalsto draw ellipses or circles. Ovalsarejust like rectangles with overly rounded corners. 

I n fact, you draw them using the same four arguments: thex and y of the top corner, and the 




width and height oftheoval itself. N otethat, because you’redrawing an oval, the starting point 
issomedistanceto the left and up from the actual outline of the oval itself. Again, if you think 
of it as a rectangle, it’s easier to place. 



Aswith the other drawing operations, thedrawovai method drawsan outlineof an oval, and the 
tiiiovai method draws a filled oval. 

H ere’san example of two ovals, a circle and an ellipse (Figure 9.9 shows how these two ovals 
appear on screen): 

public void paint (Graphics g) { 
g . d rawO val (20,20,60,60) ; 
g . f illOval (120,20,100,60); 




Figure 9.9. 

Ovals 




Arc 

Of the drawing operations, arcs are the most complex to construct, which is why I saved them 
for last. An arc is a part of a oval; in fact, the easiest way to think of an arc is as a section of a 
complete oval. Figure 9.10 shows some arcs. 



Figure 9.10. 

Arcs 




J 
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ThedrawArc method takes six arguments: the starting corner, the width and height, the angle 
at which to start thearc, and thedegreesto draw it beforestopping. 0 nee again, thereisadrawArc 
method to draw the arc’s outline and themiArc to fill thearc. Filled aresaredrawn as if they 
were sections of a pie; instead of joining the two endpoints, both endpoints are joined to the 
center of the circle. 

The important thing to understand about arcs is that you’re actually formulating the arc as an 
oval and then drawing only some of that. T he starting corner and width and height are not the 
starting point and width and height of the actual arc as drawn on the screen; they’re the width 
and height of thefull ellipse of which thearc is a part. Those first pointsdeterminethesizeand 
shape of the arc; the last two arguments (for the degrees) determine the starting and ending 
points. 

Let's start with asimplearc, aC shape on a circle as shown in Figure 9.11. 

Figure 9.11. 

A C arc. 




T o construct the method to draw thisarc, thefirst thing you do isthink of it asacompletecircle. 
T hen you find thex and y coordinates and thewidth and height of that circle. T hosefou rvalues 
are the first four argumentsto thedrawArc or miArc methods. Figure 9.12 shows how to get 
those values from thearc. 



Figure 9.12. 

Constructing a circular arc. 
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To get the last two arguments, think in degrees around the circle. Zero degrees is at 3 o’clock, 
90 degreesisat 12 o’clock, 180 at 9 o'clock, and 270 at 6 o’clock. T hestart of thearc isthedegree 
value of the start of thearc. I n this example, the starting point is the top of the C at 90 degrees; 
90 is the fifth argument. 

Thesixth and last argument isanotherdegree valueindicatinghow far around thecirdeto sweep 
and the direction to go in (it’s not the ending degree angle, as you might think). In thiscase, 
because you’re going halfway around the circle, you’re sweeping 180 degrees- and 180 is 
therefore the last argument in thearc. The important part isthat you 're sweeping 180 degrees 
counterclockwise, which is in the positive direction in Java. If you aredrawingabackwardsC, 
you sweep 180 degrees in the negative direction, and the last argument is-iso. SeeFigure9.13 
for the final illustration of how this works. 



Note: It doesn’t matter which side of the arc you start with; because the shape of 
thearc has already been determined by the complete oval it’s a section of, starting 
at either endpoint will work. 



Figure 9.13. 

A res on circles 




H ere’s the code for this example; you’ll draw an outline of the C and a filled C to its right, as 
shown in Figure 9.14: 

public void paint (Graphics g) { 
g.drawArc(20,20,60,60,90,180) ; 
g .fillArc (120, 20,60, 60,90, 1 80) ; 

> 



Cirdesareaneasywaytovisualizearcson circles; arcson ellipses areslightlymoredifficult. Let’s 
go through this same process to draw thearc shown in Figure 9.15. 
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Figure 9.14. 

Two circular arcs 



Figure 9.15. 

An elliptical arc. 



i 




Like the arc on thecircle, thisarc isa piece of a complete oval, inthiscase, an elliptical oval. By 
completing the oval that thisarc isa part of, you can get the starting points and thewidth and 
height arguments for the drawArc ormiArc method (Figure 9.16). 

Figure 9.16. < mo >■ 

A res on ellipses ^ 

30 

I 

Then, all you need is to figure out the starting angle and the angle to sweep. Thisarc doesn’t 
start on a nice boundary such as 90 or 180 degrees, so you’ll need some trial and error. T hisarc 
starts somewhere around 25 degrees, and then sweeps clockwise about 130 degrees (Figure 
9.17). 





o° 



Figure 9.17. 

Starting and ending points 



180° 




With all portions of the arc in place, you can write the code. H ere’sthejava code for this arc, 
both drawn and filled (notein thefilled casehowfilled arcsaredrawn asif they werepiesections): 

public void paint (Graphics g) { 

g . drawArc (10,20,150,50,25, -130); 
g . f illArc (10,80,150,50,25, -130); 

> 

Figure 9.18 shows the two elliptical arcs. 




T o summarize, here are the steps to take to construct arcs in J ava: 

0 T hink of the arc as a slice of a complete oval. 

B; Construct the full oval with the starting point and the width and height (it often helps 
to draw the full oval on the screen to get an idea of the right positioning). 

□ Betermi ne the starti ng angle for the beginning of the arc. 

□ D etermine how far to sweep the arc and in which direction (counterclockwise 
indicates positive values, clockwise indicates negatives). 

A Simple Graphics Example 

H ere’s an example of an applet that uses many of the built-in graphics primitives to draw a 
rudimentary shape. I n this case, it’s a lamp with a spotted shade (or a sort of cubist mushroom, 
depending on your point of view). Listing 9.1 hasthecompletecodeforthelamp; F igure 9.19 
shows the resulting applet. 
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Figure 9.19. 

The Lamp applet. 
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public void paint (Graphics g) { 
// the lamp platform 
g.fillRect(0, 250,290, 290) ; 
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// the base of the lamp 
g . drawLine (125, 250 ,125,160) ; 
g.drawLine(175,250, 175,160) ; 

// the lamp shade, top and bottom edges 
g.drawArc(85,157, 130,50, -65,312) ; 
g . drawArc (85,87,130,50,62,58); 

// lamp shade, sides 
g. drawLine (85, 177, 11 9, 89) ; 
g. drawLine (21 5, 177, 181 ,89) ; 

// dots on the shade 
g .f illArc(78, 120, 40,40, 63, - 1 74) ; 
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23: g.fillOval(120,96,40,40) ; 

24: g.fillArc( 173, 100, 40,40, 11 0,180); 

25: } 

26: } 



Copying and Clearing 

0 nceyou’vedrawn afew thingson thescreen, you may wantto move them around or clear the 
entire applet. T he Graphics class provides methods for doing both these things. 

The copyArea method copies a rectangular area of the screen to another area of the screen. 
copyArea takes six arguments: the x and y of the top corner of the rectangle to copy, the width 
and the height of that rectangle, and the distance in thex and y directions to which to copy it. 
For example, this line copies a square area 100 pixels on aside 100 pixels directly to its right: 

g. copyArea (0,0, 100, 100, 100,0) ; 

T 0 dear a rectangular area, use the ciearRect method. ciearRect, which takes the same four 
arguments as the drawRect and miRect methods, fills the given rectangle with the current 
background color of the applet (you’ll learn how to set the current background color later on 
today). 

T 0 clear the entire applet, you can usethesizeo method, which returns a Dimension object 
representing the width and height of the applet. You can then get to theactual valuesfor width 
and height by using the width and height instance variables: 

g . ciearRect ( 0 , 0 , this . size ( ) .width , this . height ( ) ) ; 

Text and Fonts 

T heoraphics classalso enablesyou to printtext on thescreen, in conjunction with theFont class, 
and, sometimes, theFont metrics class. TheFont cl ass represents a given font- itsname, style, 
and point size — and Font metrics givesyou information about that font (for example, theactual 
height or width of a given character) so that you can precisely lay out text in your applet. 

Note that the text hereisstatictext, drawn to thescreen once and intended to stay there. You’ll 
learn about entering text from the keyboard later on this week. 

Creating Font Objects 

T o draw text to the screen, first you need to create an instance of the Font class. Font objects 
represent an individual font— that is, itsname, style (bold, italic), and point size. Font names 
are strings representing the family of the font, for example, "TimesRoman", "courier", or 
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"Helvetica". Font styles are constants defined bytheFont class; you can get to them using class 
variables— forexample, Font . plain, Font . bold, or Font . italic. Finally, thepoint sizeisthesize 
of the font, as defined by the font itself; the point size may or may not be the height of the 
characters. 

T ocreatean individual fontobject,usethesethreeargumentstotheFontdass’snew constructor: 

Font f = new Font("TimesRoman" , Font. BOLD, 24); 

T hisexamplecreatesafont object for theiimesRoman bold font, in 24 points. N ote that I ike most 
J ava classes, you have to import this class before you can use it. 

Font styles are actually integer constants that can be added to create combined styles; for 
example, Font, bold + Font, italic produces a font that is both bold and italic. 

The fonts you haveavailableto you in your applet depend on the system on which the applet 
is running. Currently, although there is a mechanism in Java to get a list of fonts (see the 
getFontList method, defined in the j ava. awt. Toolkit class), it appears not to be working 
currently in the beta version oftheJDK. Once these capabilitieswork, it is possibleto get a list 
of fonts on the system and to be able to make choices based on that list; for now, to make sure 
your applet iscompletelycompatibleacross systems, it'saverygood idea to limit thefonts you 
usein your applets to “TimesRomarr, "Helvetica", and "courier". If J ava can’t find afontyou 
want to use, it will substitute some default font, usually C ourier. 

D rawing C haracters and Strings 

With a font object in hand, you can draw text on the screen using the methodsdrawchars and 
drawstring. First, though, you need to set thecurrent font to your font object using thesetFont 
method. 

Thecurrent font ispart of thegraphicsstatethat iskept track of by theGraphics object on which 
you’re drawing. Each time you draw a character or a string to the screen, that text is drawn by 
using the current font. T o change the font of the text, first change the current font. H ere’s a 
paint o method that creates a new font, sets the current font to that font, and draws the string 
"This is a big font .", starting from the point 10, 100. 

public void paint (Graphics g) { 

Font f = new Font ( "TimesRoman" , Font. PLAIN, 72) ; 
g.setFont(f) ; 

g.drawStringj "This is a big font. " ,10, 100) ; 

} 

T his should all look familiar to you; this is how the H ello applets throughout this book were 
produced. 

T he latter two arguments to drawstring determine the point where the string will start. T hex 
value is the start of the leftmost edge of the text; y is the baseline for the entire string. 



Similar to drawstring isthedrawchars method that, instead of taking a string as an argument, 
takes an array of characters, drawchars has five arguments: thearray of characters, an n integer 
representing the first character in thearray to draw, another integer for the last character in the 
array to draw (all characters between thefirst and last aredrawn), and thex and y for the starting 
point. M OSt Of the time, drawstring is more useful than drawChars. 



Listing 9.2 shows an applet that draws several lines of textin different fonts; Figure9.20 shows 
the result. 
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Listing 9.2. Many different fonts. 

import java.awt.Font; 
import java. awt. Graphics; 

public class ManyFonts extends java. applet. Applet { 

public void paint (Graphics g) { 

Font f = new Font( "TimesRoman" , Font. PLAIN, 18); 

Font fb = new Font("TimesRoman", Font. BOLD, 18); 

Font fi = new Font("TimesRoman", Font. ITALIC, 18); 

Font fbi = new Font( “TimesRoman" , Font. BOLD + Font. ITALIC, 18); 

g.setFont(f) ; 

g. drawstring (“This is a plain font", 10, 25); 
g.setFont(fb) ; 

g. drawstring (“This is a bold font", 10, 50); 
g.setFont(fi) ; 

g. drawstring (“This is an italic font", 10, 75); 
g.setFont(fbi) ; 

g. drawstring (“This is a bold italic font", 10, 100); 



} 



Figure 9.20. 

The output of the 
M anyFonts applet. 



This is a plain font 

This is a bold font 

This is an italic font 

This is a bold italic font 
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Finding Out Information About a Font 

Sometimes, you may wantto makedecisionsin yourjava program based on thequalitiesof the 
current font— for example, its point size, or the total height of its characters. You can find out 
some basic information about fonts and font objects by using simple methodson Graphics and 
on the Font objects. T able 9.1 shows some of these methods: 



Table 9.1. Font methods. 




Method Name 


1 n 0 bject 


Action 


getFont() 


Graphics 


Returns the current font object as previously set by 

setFont() 


getName( ) 


Font 


Returns the name of the font as a string 


getSize() 


Font 


Returns the current fontsize(an integer) 


getstyle() 


Font 


Returns the current style of the font (styles are integer 
constants: 0 is plain, 1 is bold, 2 is italic, 3 is bold italic) 


isPlain() 


Font 


Returns true or false if the font’s style is plain 


isBold() 


Font 


Returns true or false if the font’s style is bold 


isltalic() 


Font 


Returns true or false if the font’s style is italic 



For more detailed information about thequalitiesof the current font (for example, the length 
or height of given characters), you need to work with font metrics. The FontMetrics class 
describes information specific to a given font: the leading between lines, the height and width 
of each character, and so on. To work with these sorts of values, you create a FontMetrics object 
based on the current font by using the applet method getFontMetnics: 

Font f = new Font("TimesRoman" , Font. BOLD, 36); 

FontMetrics fmetrics = getFontMetrics(f ) ; 
g.setfont(f ) ; 

T able9.2 showssomeof thethingsyou can find out usingfont metrics. All thesemethodsshould 
be called on a FontMetrics object. 

Table 9.2. Font metrics methods. 

Method Name Action 

stringwidtho Given a string, returns the full width of that string, in pixels 
charwidtho Given a character, returns the width of that character 



166 



Method Name 


Action 


getAscent() 


Returns the ascent of the font, that is, the distance between the 
font’s baseline and the top of the characters 


getDescent() 


Returns the descent of the font— that is, the distance between the 
font’s baseline and the bottoms of the characters (for characters such 
as p and q that drop below the baseline) 


getLeading() 


Returns the leading for thefont, that is, the spacing between the 
descent of one line and the ascent of another line 


getHeight() 


Returns the total height of the font, which is the sum of the ascent, 
descent, and leading value 



Asan example of the sorts of information you can use with font metrics, Listing 9.3 shows the 
J ava codefor an applet that automatically centers a string horizontally and vertically inside an 
applet. The centering position is different depending on thefont and font size; by using font 
metrics to find out the actual size of a string, you can draw the string in the appropriate place. 



N ote the applet, size o method here, which returns the width and height of the overall applet 
areaasaDimension object. You can then gettotheindividual width and height by usingthewidth 
and height instance variables. 



Figure 9.21 shows the result (less interesting than if you actually compileand experiment with 
various applet sizes). 
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Listing 9.3. Centering a string. 
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import j ava. awt. Font; 
import java. awt. Graphics; 
import java. awt. FontMetrics; 

public class Centered extends java. applet. Applet { 

public void paint (Graphics g) ( 

Font f = new Font("TimesRoman" , Font. PLAIN, 36); 
FontMetrics fm = getFontMetrics(f ) ; 
g.setFont(f) ; 

String s = "This is how the world ends."; 

int xstart = (this. size() .width - fm.stringWidth(s)) / 2; 

int ystart = (this. size() .height - fm.getHeightO) / 2; 



g. drawstring (s, xstart, ystart); 
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Figure 9.21. 

T he centered text. 



This is how the world ends. 



Color 

D rawing black linesand testson agray background isall very nice, but being ableto usedifferent 
colors is much nicer. Java provides methods and behaviors for dealing with color in general 
through the color class, and also provides methods for setting the current foreground and 
background colors so that you can draw with the colors you created. 

Java's abstract color model uses 24-bit color, wherein a color is represented asacombi nation of 
red, green, and bluevalues. Each component of thecolor can havea number between 0 and 255. 
0,0,0 isblack, 255,255,255 iswhite, and Java can represent millionsof colors between aswell. 

J ava’sabstract color model mapsonto thecolor model of theplatform J ava isrunni ng on, which 
usually hasonly 256 colors or fewer from which to choose. I f a requested color in a color object 
isnot availablefor display, theresultingcolor may bemapped to another or dithered, depending 
on how thebrowser viewing thecolor implemented it, and depending on theplatform on which 
you’re running. In other words, although Java gives the capability of managing millionsof 
colors, very few may actually be available to you in real life. 



Using Color Objects 

T 0 draw an object in aparticular color, you must createan instanceof thecolor dassto represent 
that color. Thecolor class defines a set of standard color objects, stored in cl ass variables, that 
enable you quickly to get a color object for some of the more popular colors. For example, 
color, red givesyou a color object representing red (RGB valuesof255, 0, and 0), color, white 
gives you a white color (RG B values of 255, 255, and 255), and so on. T able 9.3 shows the 
standard colors defined by variables in the color class. 



Table 9.3. Standard colors. 

Color Name RGB Value 

Color. white 255,255,255 

Color. black 0,0,0 



Color. lightGray 192,192,192 
Color. gray 128,128,128 
Color. darkGray 64,64,64 




Color Name 



RGB Value 



Color. red 
Color. green 
Color. blue 
Color. yellow 
Color. magenta 
Color. cyan 
Color. pink 
Color. orange 



255.0. 0 
0,255,0 
0,0,255 

255.255.0 

255.0. 255 
0,255,255 
255,175,175 

255.200.0 



If the color you want to draw in isnotoneofthestandard color objects, fear not. You can create 
a color object for any combination of red, green, and blue, aslongasyou have the values of the 
color you want. J ust create a new color object: 

Color c = new Color(140, 140, 140) ; 

This line of Java code creates a color object representing a dark grey. You can use any 
combination of red, green, and blue values to construct a color object. 

Alternatively, you can also create a color object using three floats from 0.0 to 1 .0: 

Color c = new Color(0. 34, 1 .0,0.25) 

Testing and Setting the Current Colors 

Todrawan object or text using a color object, you have to set the current colorto be that color 
object, just as you have to set the current font to the font in which you want to draw. U sethe 
setcoior method (a method for Graphics objects) to do this: 

g. setColor(Color. green) ; 

After setting the current color, all drawing operations will occur in that color. 

I n addition to setting thecurrent color for thegraphics context, you can also set the background 
and foreground colors for the applet itself by using the setBackground and setForeground 
methods. Both of these methods are defined in the j ava . awt . component class, which Applet— 
and therefore your classes- automatically inherits. 

T hesetBackground method setsthebackground color of theapplet, which isusually adark grey. 
It takes a single argument, a color object: 

setBackground(Color. white) ; 
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ThesetForeground method also takes a si ngle color as an argument, and affects everything that 
has been drawn on the applet, regardless of the color in which it has been drawn. You can use 
setForeground to change the color of everything in the applet at once, rather than having to 
redraw everything: 

setForeground(Color. black) ; 

I n addition to thesetcoior, setForeground, and setBackground methods, there arecorrespond- 
ing "get” methods that enable you to retrieve the current graphics color, background, or 
foreground. T hosemethodsaregetcoior (defined in Graphics objects), getForeground (defined 
in Applet), and getBackground (also in Applet). You can use these methods to choose colors 
based on existing colors in the applet: 

setForeground(g.getColor( ) ) ; 



A Single Color Example 

Listing 9.4 shows the codefor an applet that fills the applet's drawing area with square boxes, 
each ofwhichhasarandomlychosen color in it. It'swritten sothatitcan handleany sizeof applet 
and automatically fill the area with the right number of boxes. 
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Listing 9.4. Random color boxes. 



import java.awt. Graphics; 
import java.awt. Color; 

public class ColorBoxes extends java. applet. Applet { 

public void paint (Graphics g) { 
int rval, gval, bval; 

for (int j = 30; j < (this . size (). height -25); j += 30) 
for (int i = 5; i < (this. size() .width -25); i+= 30) { 
rval = (int)Math .floor(Math . random( ) * 256); 
gval = (int)Math .floor(Math . random( ) * 256); 
bval = (int)Math .floor(Math . random( ) * 256); 
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g.setColor(new Color (rval, gval, bval) ) ; 
g.fillRect(i, j ,25,25) ; 
g.setColor(Color. black) ; 
g .drawRect (i-1 , j -1 ,25,25) ; 



Anshfdc Thetw 0 forl 00 p saretheheart 0 fthisexam P |e ; thefirst:0neclrawsther0ws ' anclthesec0ncl 
AflfliySiS draws the individual boxes within the row. W hen a box is drawn, the random color is 




calculated first, and then the box is drawn. A black outline is drawn around each box, because 
some of them tend to blend into the background of the applet. 

Because this paint method generates new colors each time the applet is painted, you can 
regenerate the colors by moving the window around or by covering the applet's window with 
another one. Figure 9.22 shows the final applet (although given that this picture is black and 
white, you can’t get the full effect of the multicolored squares). 



Figure 9.22. 

The random colors applet. 
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Summary 

You present something on thescreen by painting insideyour applet: shapes, graphics, text, or 
images. T oday, you learned the basicsof how to paint, including using the graphics primitives 
to draw rudimentary shapes, using fonts and font metrics to draw text, and usingcoior objects 
to change the color of what you're drawing on thescreen. It’sthisfoundation in painting that 
enables you to do animation insidean applet (which basically involvesjust painting repeatedly 
to thescreen) and to work with images. These are topics you’ll learn about tomorrow. 



Q&A 

Q I n all the examples you show, and in all the tests I 've made, the graphics primi- 
tives, such as drawLine and drawRect, produce lines that are one pixel wide. H ow 
can I draw thicker lines? 

A I n the current state of thej ava G raphics class, you can’t; no methods exist for chang- 
ing the default line width. If you really need a thicker line, you have to draw multiple 
lines one pixel apart to produce that effect. 

Q I wrote an applet to use H elvetica. It worked fine on my system, but when I run 
it on my friend's system, everything is in Courier. Why? 
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A Yourfriend most likely doesn’t have the H elvetica font installed on hisor her system. 
When Java can’t find a font, it substitutes a default font instead— in your case, 

Courier. The best way to deal with this is to query the font list. As I’m writing this, 
however, querying the font list doesn’t yet work, so your safest bet is to stick with 
either T imes Roman or C ourier in your applets. 

Q I tried out that applet that draws boxes with random colors, but each time it 
draws, a lot of the boxes are the same color. I f the colors are truly random, why is 
it doing this? 

A Two reasons. The first is that the random number generator I used in that code (from 
the Math class) isn’t a very good random number generator; in fact, the documentation 
for that method saysasmuch. For a better random number generator, use the Random 
class from thejavautil package. 

The second, morelikely, reason isthat there just aren't enough colors available in your 
browser or on your system to draw all the colors that the applet is generating. If your 
system can’t produce the wide range of colors available using the color class, or if the 
browser has allocated too many colors for other things, you may end up with duplicate 
colors in the boxes, depending on how the browser and the system has been written to 
handle that. Usually your applet won’t use quite so many colors, so you won't run 
into this problem quite so often. 
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The first thing I ever saw Java do was an animation: a large red "Hi there!" that ran across the 
screen from theright to left. Even that simpleform of animation was enough to makemestop 
and think, "this is really cool.” 

That sort of simple animation takes only a few methods to implement in Java, but those few 
methods are the basis for any Java applet that you want to update the screen dynamically. 
Starting with simple animations is a good way to build up to the more complicated applets. 
T oday, you’ll learn thefundamentalsof animation in Java: how the various parts of the system 
all work together so that you can create moving figures and dynamic updateable applets. 
Specifically, you’ll explore the following: 

□ H ow Java animations work— the paint o and repaint o methods, starting and 
stopping dynamic applets, and how to use and override these methods in your own 
applets 

Z T hreads- what they are and how they can make your applets more well-behaved with 
other applets and with thejava system in general 

□ Reducing animation flicker, a common problem with animation in Java 

Throughout today, you’ll also work with lotsof examples of real applets that create animations 
or perform some kind of dynamic movement. 

Creating Animation in J ava 

Animation injavainvolvestwo steps: constructing a frame of animation, and then askingjava 
to paint that frame. Repeat as necessary to create the illusion of movement. The basic, static 
applets that you created yesterday taught you how to accomplish thefirst part; all that’s left is 
how to tell J ava to paint a frame. 

Painting and Repainting 

Thepainto method, as you learned yesterday, is called byj ava whenever the applet needs to 
be painted— when the applet is initially drawn, when the window containing it is moved, or 
when another window is moved from over it. You can also, however, ask Java to repaint the 
applet at atimeyou choose. So, to changetheappearanceof what ison thescreen, you construct 
the image or "frame” you want to paint, and then ask Java to paint this frame. If you do this 
repeatedly, and fast enough, you get animation insideyour J ava applet. T hat'sall thereisto it. 

Where does all this take place? Not in thepainto method itself. All paint o does is put dots 
on thescreen. paint o, in other word s,isresponsibleonlyforthecurrentframeoftheanimation 
at a time. The real work of changing what paint o does, of modifying the frame for an 
animation, actually occurs somewhere else in the definition of your applet. 



174 



In that "somewhere else,” you construct theframe (set variablesfor paint o to use, create color 
or font or other objectsthat paint o will need), and then call the repaint < > method, repaint ( ) 
is the trigger that causesjavato call paint o and causes your frame to get drawn. 




Technical Note: Because ajava applet can contain many different components 
that all need to be painted (as you’ll learn later on this week), and in fact, applets 
are embedded inside a larger Java application that also paints to the screen in 
similar ways, when you call repainto (and therefore paint o) you’re not actually 
immediately drawing to the screen as you do in other window or graphics toolkits. 
Instead, repainto is a request for Java to repaint your applet as soon as it can. 

M uch of the time, the delay between the call and the actual repaint is negligible. 



Starting and Stopping 
an Applet's Execution 

Remember start q and stopo from Day 8?These are the methodsthat trigger your applet to 
start and stop running. You didn't usestarto and stopo yesterday, because theappletson that 
day did nothing except paint once. With animations and other Java applets that are actually 
processing and running overtime, you’ll need to makeuseof start o and stopo to trigger the 
start of your applet’s execution, and to stop it from running when you leave the page that 
containsthat applet. For most applets, you’ll wanttooverridestart and stop for justthisreason. 

Thestarto method triggers theexecution oftheapplet.You can either do all theapplet’swork 
inside that method, or you can call other object’s methods in order to do so. U sually, start q 
is used to create and begin execution of a thread so the applet can run in its own time. 

stopo, on the other hand, suspects an applet's execution so when you move off the page on 
which the applet isdisplaying, it doesn't keep running and using up system resources. M ost of 
the time when you create a start o method, you should also create a corresponding stopo. 

Putting It Together 

Explaining how to do Java animation in text is more of a task than actually showing you how 
it worksin code. An exampleor two will help make the relationship between all these methods 
clearer. 

Listing 10.1 shows a sample applet that, at first glance, uses basic applet animation to display 
thedateandtimeand constantly updatesit every second, creatingaverysimpleanimated digital 
clock (a frame from that clock is shown in Figure 10.1). 
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T he words "at first glance" in the previous paragraph are very important: this applet doesn't 
work! H owever, despite the fact that it doesn't work, you can still learn a lot about basic 
animation with it, so working through thecodewill still be valuable. In the next section, you’ll 
learn just what’s wrong with it. 



See whether you can figure out what’sgoing on with this code before you go on to theanalysis. 
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Listing 10.1. The Date applet. 

import java.awt. Graphics; 
import java.awt. Font; 
import java. util. Date; 

public class DigitalClock extends java. applet. Applet { 

Font theFont = new Font ( "TimesRoman" , Font .BOLD, 24) ; 
Date theDate; 

public void start () { 
while (true) { 

theDate = new Date(); 
repaint () ; 

try { Thread. sleep(1000) ; } 
catch (InterruptedException e) { > 



public void paint(Graphics g) { 
g.setFont(theFont) ; 

g. drawstring (theDate. toSt ring () , 10,50) ; 

> 

} 



Figure 10.1. 

The digital clock. 



Sun Nov 05 20:43:02 PST 1995 




T hink you’ve got the basic idea? Let’s go through it, line by line. 



Lines 7 and 8 define two basic instance variables: theFont and theDate, which hold objects 
representing the current font and the current date, respectively. M ore about these later. 
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Thestarto method triggers the actual execution of theapplet. N otethewmie loop insidethis 
method; given that the test (true) always returnstrue, theloop never exits. A singleanimation 
frame is constructed inside that while loop, with the following steps: 

Jut T he Date class represents a date and time (Date is part of the j ava . utu package- note 
that it was specifically imported in line three). Line 12 creates a new instance of the 
Date class, which holds the current date and time, and assigns it to thetheDate 
instance variable. 

□ T he repaint o method is called. 

□ Lines 14 and 15, ascomplicated asthey look, do nothing except pausefor 1000 
milliseconds (one second) before theloop repeats. The sleep 0 method there, part of 
the Thread class, iswhat causes the applet to pause. Without a specific sleep 0 
method, theapplet would run as fast as it possibly could, which, for faster computer 
systems, might be too fast for the eye to see. Using sieepo enables you to control 
exactly how fast the animation takes place. The try and catch stuff around it enables 
J ava to manage errors if they occur, try and catch are called exceptions and are 
described on D ay 18, next week. 

On to the paint o method. H ere, inside paint 0, all that happens is that the current font (in 
thevariabletheFont) isset, and the date itself is printed to thescreen (notethatyou have to call 
thetostringo method to convert thedateto astring). Because paint 0 iscalled repeatedly with 
whatever value happens to be in theDate, the string is updated every second to reflect the new 
date. 

There are a few things to note about this example. First, you might think it would be easier to 
create the new Date object inside the paint o method. That way you could use a local variable 
and not need an instance variable to pass the Date object around. Although doing things that 
way creates cleaner code, it also resultsin a less efficient program. T hepamt < > method iscalled 
every time a frame needs to be changed. In this case, it’s not that important ), but in an 
animation that needsto change frames very quickly, thepaint ( ) method hasto pause to create 
that new object every time. By leaving paint 0 to do what it does best- painting thescreen — 
and calculating new objects before hand, you can make painting as efficient as possi ble. T his is 
precisely the same reason why the Font object is also in an instance variable. 

Threads: What They Are 
and Why You Need Them 

Depending on your experience with operating systems and with environments within those 
systems, you may or may not have run into theconcept of threads. Let'sstart from thebeginning 
with some definitions. 
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When a program runs, it starts executing, runs its initialization code, calls methods or 
procedures, and continues running and processing until it’s complete or until the program is 
exited. That program usesa singlethread — where thethread isa single locus of control for the 
program. 

M ultithreading, as in Java, enables several different execution threadsto run at the same time 
inside the same program, in parallel, without interfering with each other. 

H ere's a simple example. Suppose you have a long computation near the start of a program's 
execution. This long computation may not be needed until later on in the program’s 
execution— it’s actually tangential to the main point of the program, but it needs to get done 
eventually. In asingle-threaded program, you haveto wait for that computation to finish before 
the rest of the program can continue running. In a multithreaded system, you can put that 
computation into its own thread, enabling the rest of the program to continue running 
independently. 

U singthreadsinj ava, you can createan applet so that it runsin itsown thread, and it will happily 
run all by itself without interfering with any other part of the system. Using threads, you can 
have lots of applets running at once on the same page. D epending on how many you have, you 
may eventually exhaust the system so that all of them will run slower, but all of them will run 
independently. 

Even if you don’t have lots of applets, using threadsin your appletsisgood Java programming 
practice. The general rule of thumb for well-behaved applets: whenever you have any bit of 
processing that is likely to continuefor a long time (such as an animation loop, or a bit of code 
that takesa long time to execute), put it in athread. 

The Problem with the Digital Clock Applet 

T hat D igital C lock applet in thelast section doesn't usethreads. I nstead, you put thewhiie loop 
that cydesthroughtheanimation directly into thestarto method so that when theapplet starts 
running it keeps going until you quit the browser or applet viewer. Although thismay seem like 
agood way to approach the problem, thedigital clock won’t work because thewhiie loop in the 
start o method ismonopolizingall theresourcesin the system— including painting. If you try 
compiling and running thedigital clock applet, all you get isa blank screen. You also won’t be 
ableto stop the applet, because there’s no way a stop o method can ever be called. 

The solution to this problem is to rewrite the applet to usethreads. Threads enable this applet 
to animate on itsown without interfering with other system operations, enable it to be started 
and stopped, and enable you to run it in parallel with other applets. 
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Writing Applets with Threads 

H ow do you create an applet that uses threads? There are several things you need to do. 
Fortunately, noneofthem aredifficult, and a lot of the basics of using threads in applets isjust 
boilerplate code that you can copy and paste from one applet to another. Because it's so easy, 
there's almost no reason not to use threads in your applets, given the benefits. 

There are four modifications you need to make to create an applet that uses threads: 

D Change the signature of your applet class to include the words implements Runnable. 

□ Include an instance variable to hold this applet's thread. 

£) 1 odify your start o method to do nothing but spawn a thread and start it running. 

□ Createaruno method that contains the actual code that starts your applet running. 
Thefirst changeisto thefirst lineof your cl assdefinition. You’ve already got something likethis: 

public class MyAppletClass extends java. applet. Applet { 

> 

You need to change it to the following (I’ve put it on two lines so it’ll fit on this page; it can be 
either likethisoron one line depending on your preference): 

public class MyAppletClass extends java. applet. Applet implements Runnable { 

} 

What does this do? It includes support for the Runnable interface in your applet. If you think 
way back to D ay 2, you’ll remember that interfaces are a way to collect method names common 
to different classes, which can then be mixed in and implemented inside different classes that 
need to implementthat behavior. H ere, theRunnabie interfaceindudesthebehavioryourapplet 
needs to run athread; in particular, it gives you a default definition fortheruno method. 

Thesecond step isto add an in stance variable to hold this applet’s thread. Call it anything you 
like; it’s a variable of the type Thread (Thread isa classin java.iang, so you don’t have to import 
it): 

Thread runner; 

T hird, add a start < > method or modify theexisti ng oneso that it does nothing but createa new 
thread and start it running. H ere’s a typical example of a start o method: 

public void start () { 

if (runner == null); { 

runner = new Thread(this) ; 
runner. start() ; 

} 
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If you modify start o to do nothing but spawn a thread, where does the body of your applet 
go? It goes into anew method, runo, which looks like this: 

public void run() { 

// what your applet actually does 

> 

run( ) can contain anythingyou want to run in the separate thread: initialization code, theactual 
loop for your applet, or anything else that needs to run in its own thread. You also can create 
new objects and call methodsfrom insideruno, and they’ll also run insidethat thread. Therun 
method is the real heart of your applet. 

Finally, now that you’ve got threads running and astart method to start them, you should add 
astopo method to suspend execution of that thread (and thereforewhatevertheappletisdoing 
at the time) when the reader leaves the page, stopo, like start <>, is usually something along 
these lines: 

public void stop() { 

if (runner != null) { 
runner. stop() ; 
runner = null; 

> 

} 

The stopo method here does two things: it stops the thread from executing and also sets the 
thread's variable (runner) to null. Setting the variable to nun makes the Thread object it 
previously contained available for garbage collection so that the applet can be removed from 
memory after a certain amount of time. If the reader comes back to this page and this applet, 
the start method creates a new thread and starts up the applet once again. 

And that’sit! Four basic modifications, and now you have a well-behaved applet that runsin its 
own thread. 

FixingThe Digital Clock 

Rem ember theproblemsyou had with theDigital Clock applet at the beginning of thissection? 
Let’sfix them so you can get an idea of how a real applet with threads looks. You’ll follow the 
four steps outlined in the previous section. 

First, modify the class definition to include the Runnable interface (the class is renamed to 

DigitalThreads instead Of DigitalClock): 

public class DigitalThreads extends java. applet. Applet 
implements Runnable { 



Second, add an instance variable for the Thread: 

Thread runner; 



180 



For the third step, swap the way you did things. Because the bulk of the applet is currently in 
a method called start o, but you want it to be in a method called runo, rather than do a lot 
of copying and pasting, just rename the existing start o to runo: 

public void run() { 

while (true) { 



Finally, add the boilerplate start o and stopo methods: 

public void start () { 

if (runner == null) ; { 

runner = new Thread(this) ; 
runner. start() ; 

} 

} 



public void stop() { 

if (runner != null) { 
runner. stop( ) ; 
runner = null; 



You'refinished! 0 neapplet converted to use threads in lessthan aminuteflat.Thecodeforthe 
final applet appears in Listing 10.2. 
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Listing 10.2. The fixed digital clock applet. 
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import java.awt. Graphics; 
import java.awt. Font; 
import java. util. Date; 

public class DigitalThreads extends java. applet .Applet 
implements Runnable { 

Font theFont = new Font ( "TimesRoman” .Font .BOLD, 24) ; 
Date theDate; 

Thread runner; 

public void start () { 

if (runner == null) ; { 

runner = new Thread(this) ; 
runner. start() ; 

} 

> 

public void stop() { 

if (runner != null) { 
runner. stop() ; 
runner = null; 

} 

> 



continues 
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Listing 10.2. continued 



25: 

26: public void run() { 

27: while (true) { 

28: theDate = new Date ( ) ; 

29: repaint(); 

30: try { Thread . sleep(1 000) ; > 

31: catch (InterruptedException e) { } 

32: > 

33: > 

34: 

35: public void paint (Graphics g) { 

36: g.setFont(theFont) ; 

37: g.drawString(theDate.toString() ,10,50) ; 

38: } 

39: } 

40: 



Reducing Animation Flicker 

If you’ve been following along with this book and trying the examples as you go, rather than 
reading this book on the airplane or in the bathtub, you may have noticed that when the date 
program runs every once in a while, there's an annoying flicker in the animation. (N ot that 
there’s anything wrong with reading this book in the bathtub, but you won't see the flicker if 
you do that, so just trust me— there’saflicker.) T his isn't a mistakeor an error in the program; 
in fact, that flicker is a side effect of creating animations in Java. Because it is really annoying, 
however, you’ll learn how to reduceflickerin this part of today’s lesson so that your animations 
run cleaner and look better on the screen. 

Flicker and Howto Avoid It 

Flicker is caused by the way Java paints and repaints each frameof an applet. At the beginning 
of today’slesson, you learned that when you call therepamt < ) method, repaint ( > callspaint o. 
That'snot precisely true. A call to painto doesindeed occur in response to a repaint o, but 
what actually happens are the following steps: 

1. Thecall to repaint o results in a call to the method updateo. 

2. Theupdateo method clears the screen of any existing contents (in essence, fillsitwith 
the current background color), and then calls painto. 

3. The painto method then draws the contents of the current frame. 

It's Step 2, thecall to updateo, that causes animation flicker. Because the screen is cleared 
between frames, thepartsofthescreen that don’t changealternaterapidly between being painted 
and being cleared. H ence, flickering. 
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T here are two major ways to avoid flicker i n your J ava applets: 

□ 0 verride update ( > either not to clear the screen at all, or to clear only the parts of the 
screen you’ve changed. 

□ Override both update o and paint o, and use double-buffering. 

I f the second way sounds complicated, that's because it is. Double-buffering involves drawing 
to an offscreen graphics surface and then copying that entire surface to the screen. Because it’s 
more complicated, you’ll explore that one tomorrow. T oday, let’s cover the easier solution: 
overriding update. 

Howto Override Update 

The cause of flickering lies in theupdateo method. To reduce flickering, therefore, override 
both update ( ) and paint ( ) . H ere’s what thedefault version of update ( > does (in thecomponent 
class, which you’ll learn more about on Day 13): 

public void update (Graphics g) { 
g.setColor(getBackground()) ; 
g.fillRect(0, 0, width, height); 
g .setColor( get Foreground ( ) ) ; 
paint(g) ; 

> 

Basically, updateo clears the screen (or, to be exact, fills the applet’s bounding rectangle with 
the background color), sets things back to normal, and then callspainto. When you override 
updateo, you have to keep these two thingsin mind and makesurethatyourversion ofupdateo 
does something similar. In the next two sections, you’ll work through some examples of 
overriding updateo in different cases to reduce flicker. 



Solution One: Don't Clear the Screen 



T hefirst solution to reducing flicker is not to clear the screen at all. T his works only for some 
applets, of course. H ere’s an example of an applet of this type. TheColorSwirl applet prints a 
single string to the screen ("ah the swiny colors"), but that string is presented in different 
colors that fade into each other dynamically. T hisapplet flickersterribly when it’s run. Listing 
10.3 shows the source for this applet, and Figure 10.2 shows the result. 



Type 



Listing 10.3. The ColorSwirl applet. 



import j ava. awt. Graphics; 
import java. awt. Color; 
import java. awt. Font; 



continues 
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Listing 10.3. continued 
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public class ColorSwirl extends java. applet. Applet 
implements Runnable { 

Font f = new Font ( "TimesRoman" , Font .BOLD, 48) ; 

Color colorsj] = new Color[50]; 

Thread runThread; 

public void start () { 

if (runThread == null) { 

runThread = new Thread(this) ; 
runThread. start () ; 

> 

> 

public void stop() { 

if (runThread != null) { 
runThread. stop() ; 
runThread = null; 



public void run() { 

// initialize the color array 
float c = 0; 

for (int i = 0; i < colors. length; i++) { 
colors[i] = 

Color. getHSBColor(c, (float)l .0, (float)l .0) ; 
c += .02; 



// cycle through the colors 
int i = 0; 
while (true) { 

setForeground(colors[i] ) ; 

repaint () ; 

i++; 

try { Thread. sleep(50) ; > 

catch (InterruptedException e) { > 

if (i == colors. length ) i = 0; 



public void paint(Graphics g) { 
g.setFont(f) ; 

g. drawstring ("All the Swirly Colors", 15,50); 

} 
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Figure 10.2. 

TheColorSwirl applet. 



All the Swirly Colors 



There are three new things to note about this applet that might look strange to you: 

□ When the applet starts, the first thing you do (in lines 28 through 34) is to create an 
array of color objects that contains all the colors the text will display. By creating all 
the colors beforehand you can then just draw text in, one at a time; it’s faster to 
precompute all the colors at once. 

□ to create the different colors, a method in the color class called getHSBCoioro creates 
a color object based on values for hue, saturation, and brightness, rather than the 
standard red, green, and blue. This is easier; by incrementing the hue value and 
keeping saturation and brightness constant you can create a range of colors without 
having to know the RGB for each one. If you don’t understand this, don’t worry 
about it; it’s just an easy way to create the color array. 

□ The applet then cycles through the array of colors, setting the foreground to each one 
in turn and calling repaint. When it gets to the end of the array, it starts over again 
(line 44), so the process repeats over and over ad infinitum. 

Now that you understand what theapplet does, let’sfixtheflicker. Flicker here results because 
each timetheapplet ispainted, there'sa moment where thescreen isdeared. Instead of the text 
cycling neatly from red to a nice pink to purple, it’s going from red to grey, to pink to grey, to 
purple to grey, and soon— not very nice looking at all. 

Because the screen clearing is all that’s causing the problem, the solution is easy: override 
update o and remove the part wherethe screen gets cleared. It doesn’t really need to get cleared 
anyhow, because nothing is changing except the color of the text. W ith the screen clearing 
behavior removed from updateo, all update needs to do is call pamto. H ere's what the 
updateo method lookslikein this applet: 

public void update (Graphics g) { 
paint (g) ; 

} 

W ith that— with one small three-line addition— no more flicker. W asn't that easy? 
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Solution Two: Redraw 
Only What You Have To 

For some applets, it won’t be quite that easy. H ere’s another example. I n this applet, called 
C heckers, a red oval (a checker piece) moves from a black square to a white square, as if on a 
checkerboard. Listing 10.4 shows the code for this applet, and Figure 10.3 shows the applet 
itself. 
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Listing 10.4. The Checkers applet. 



1: import java.awt. Graphics; 

2: import java.awt. Color; 

3: 

4: public class Checkers extends java. applet. Applet 

5: implements Runnable { 

6: 

7: Thread runner; 

8: int xpos; 

9: 

10: public void start() { 

Its if (runner == null); { 

12: runner = new Thread(this) ; 

13: runner. start () ; 

14: > 

15: } 

16: 

17: public void stop() { 

18: if (runner != null) { 

19: runner. stop() ; 

20: runner = null; 

21: } 

22: } 

23: 

24: public void run() { 

25: setBackground(Color.blue) ; 

26: while (true) { 

27: for (xpos = 5; xpos <= 105; xpos+=4) { 

28: repaint(); 

29: try { Thread . sleep( 1 00) ; } 

30: catch (InterruptedException e) { > 

31: } 

32: for (xpos = 105; xpos > 5; xpos -=4) { 

33: repaint(); 

34: try { Thread . sleep( 1 00) ; } 

35: catch (InterruptedException e) { } 

36: } 

37: > 

38: } 

39: 

40: public void paint (Graphics g) { 

41: // Draw background 

42: g. setColor(Color. black) ; 
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43: g . f illRect (0,0,1 00 ,100) ; 

44: g. setColor(Color. white) ; 

45: g.fillRect(101, 0,100, 100); 

46: 

47: // Draw checker 

48: g.setColor(Color.red) ; 

49: g.fillOval(xpos,5,90,90) ; 

50: } 

51: } 



Figure 10.3. 

The Checkers applet. 




H ere'sa quick run-through of what thisapplet does: an instance variable, xpos, keeps track 
of the current starting position of the checker (because it moves horizontally, the y stays 
constant and the x changes). In theruno method, you change the valueof x and repaint, 
waiting 50 milliseconds between each move. The checker moves from one side of thescreen to 
the other and then moves back (hence the two for loops in that method). 

Intheactual paint o method, the background squares are painted (one black and onewhite), 
and then the checker is drawn at its current position. 

T hisapplet, liketheSwirling C olorsapplet, also hasaterribleflicker. (I n Iine25, thebackground 
is blue to emphasize it, so if you run this applet you’ll definitely see the flicker.) 

H owever, thesolution to solving theflicker problem forthisapplet ismoredifficultthan for the 
last one, becauseyou actually wantto cl ear the screen beforethenextframeisdrawn. Otherwise, 
the red checker won’t have the appearance of leaving one position and moving to another; it’ll 
just leave a red smear from one side of the checkerboard to the other. 

H owdoyou get around this?You still clear the screen, in order to gettheanimation effect, but, 
rather than clearing the entire screen, you clear only the part that you actually changed. By 
limiting the redraw to only a small area, you can eliminate much of theflicker you get from 
redrawing the entire screen. 
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T o limit what gets redrawn, you need a couple of things. First, you need a way to restrict the 
drawing area so that each timepaint < > iscalled, only thepart that needsto get redrawn actually 
gets redrawn. Fortunately, this is easy by using a mechanism called clipping. 

NEW** Clipping, part of the graphics class, enables you to restrict the drawing area to a small 
TERM portion of the full screen; although the entire screen may get instructionsto redraw, only 
the portions inside the clipping area are actually drawn. 

The second thing you need isawayto keep track of theactual area to redraw. Both the left and 
right edgesofthedrawing area changefor each frameoftheanimation (onesidetodrawthenew 
oval, the other to erase the bit of theoval left over from the previousframe), so to keep track of 
those two x values, you need instance variables for both the left side and the right. 

W ith those two conceptsin mind, let’sstart modifying theC heckers applet to redraw only what 
needsto beredrawn. First, you’ll add instance vari abl esf or th e I eft and right edgesofthedrawing 
area. Let’s call those instance variables uxi and ux2 (u for update), where uxi is the left side of 
the area to draw and ux2 the right. 

int uxi ,ux2; 

N ow let's modify the run ( ) method so that it keeps track of theactual area to be drawn, which 
you would think is easy— just update each side for each iteration of the animation. H ere, 
however, things can get complicated because of the way Java uses paint o and repamto. 

The problem with updating the edges of the drawing area with each frame of theanimation is 
that for every cal I to repainto there maynot be an individual corresponding paint o . If system 
resources get tight (because of other programs running on the system or for any other reason), 
paint o may not get executed immediately and several callsto paint o may queue up waiting 
for their turn to change thepixelson thescreen. I n thiscase, rather than trying to makeall those 
callsto paint o in order (and be potentially behind all the time), Java catches up by executing 
only the most recent call to paint o and skips all the others. 

I f you update theedgesof thedrawing area with each repaint < ) , and a coupleof callsto paint ( > 
areskipped,youendupwithbitsofthedrawingsurfacenotbeingupd ated an d bi ts of th e oval 
left behind. There’sasimpleway around this: update the leading edge of theoval each timethe 
frame updates, but only update the trailing edge if the most recent paint has actually occurred. 
This way, if a couple of callsto paint o get skipped, thedrawing area will get larger for each 
frame, and when paint o finally gets caught up, everything will get repainted correctly. 

Yes, this is horrifyingly complex. Ifl could have written this applet simpler, I would have, but 
without this mechanism theapplet will not get repainted correctly. Let’sstep through it slowly 
in the code so you can get a better grasp of what's going on at each step. 

Let'sstart with run ( > , whereeach frameoftheanimation takesplace. H ere’swhereyou calculate 
each side of the drawing area based on the old position of the oval and the new position of the 



oval. When the oval is moving toward the left side of the screen, this is easy. The value of uxi 
(the left side of the drawing area) is the previous oval’s x position (xpos), and thevalueof ux 2 
is the x position of the current oval plus the width of that oval (90 pixels in this example). 

H ere’s what the old run() method looked like, to refresh your memory: 

public void run() { 

setBackground(Color.blue) ; 
while (true) { 

for (xpos = 5; xpos <= 105; xpos+=4) { 
repaint () ; 

try { Thread. sleep(100) ; > 
catch (InterruptedException e) { > 

} 

for (xpos = 105; xpos > 5; xpos -=4) { 
repaint () ; 

try { Thread . sleep(100) ; } 
catch (InterruptedException e) { } 

} 

} 

> 

I n the first for loop in the run < ) method, where the oval is moving towardsthe right, you first 
update ux 2 (the right edge of the drawing area): 

ux2 = xpos + 90; 

Then, after the repaint o has occurred, you update uxi to reflect theoldx position oftheoval. 
H owever, you want to update this value only if the paint actually happened. H ow can you tell 
if the paint actually happened? You can reset uxi in paint o to a given value ( 0 ), and then test 
to see whether you can updatethat value or whether you have to wait for thepamto to occur: 

if (uxi == 0) uxi = xpos; 

H ere'sthenew, completed for loop for when the oval is moving to the right: 

for (xpos = 5; xpos <= 105; xpos+=4) { 
ux2 = xpos + 90; 
repaint () ; 

try { Thread. sleep(100) ; } 
catch (InterruptedException e) { } 
if (uxi == 0) uxi = xpos; 

> 

When the oval ismovingto the left, everything flips, uxi, the left side, isthe leading edge of the 
oval that getsupdated every time, and ux 2 , theright side, hastowaittomakesureitgetsupdated. 
So, in the second for loop, you first update uxi to be the x position of the current oval: 

uxi = xpos; 

Then, after the repaint o is called, you test to make sure the paint happened and update ux 2 : 

if (ux2 == 0) ux2 = xpos + 90; 
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H ere'sthenew version of thesecod tor loop inside run(>: 

for (xpos = 105; xpos > 5; xpos -=4) { 
uxl = xpos; 
repaint () ; 

try { Thread . sleep(100) ; } 
catch (InterruptedException e) { > 
if (ux2 == 0) ux2 = xpos + 90; 

> 

T hose are the only modifications run o needs. Let's override update to limit the region that is 
being painted to the left and right edgesof thedrawing area that you set insideruno. To clip 
thedrawing areato aspecific rectangle, usetheciipRect ( > method. ciipRect ( ) , likedrawRect ( ) , 
fiiiRecto, and ciearRecto, is defined for graphics objects and takes four arguments: x and 
y starting positions, and width and height of the region. 

H ere'swhereuxi and ux2 come into play, uxi isthexpoint of thetop corner of the region;then 
use ux2 to get the width of the region by subtracting uxi from that value. Finally, to finish 
update(), yOU Call paint (): 

public void update(Graphics g) { 

g.clipRect(ux1 , 5, ux2 - uxi, 95); 
paint(g) ; 

} 

N otethat with theclipping region in place, you don’t haveto do anything to theactual paint o 
method, painto goes ahead and draws to the entire screen each time, but only the areas inside 
theclipping region actually get changed on screen. 

You need to update the trailing edge of each drawing area inside paint o in case several callsto 
paint o were skipped. Becauseyou aretestingforavalueofo insideruno, you merely reset uxi 
and ux2 to 0 after drawing everything: 






0 ; 



Those are the only changes you haveto make to this applet in order to draw only the parts of 
the applet that changed (and to manage the case where some frames don’t get updated 
immediately). Although thisdoesn't totally eliminateflickering in theanimation, it does reduce 
it a great deal. T ry it and see. Listing 10.5 shows the final code for the Checkers applet. 
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Listing 10.5. The final Checkers applet. 



1: import java.awt. Graphics; 
2: import java.awt. Color; 



4: public class Checkers2 extends java. applet. Applet implements Runnable { 

5: 

6: Thread runner; 

7: int xpos; 
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public void start () { 
if (runner == null) ; { 

runner = new Thread(this) ; 
runner. start() ; 

} 



public void stop() { 

if (runner != null) { 
runner. stop() ; 
runner = null; 

} 

} 

public void run() { 

setBackground(Color.blue) ; 
while (true) { 

for (xpos = 5; xpos <= 105; xpos+=4) { 
ux2 = xpos + 90; 
repaint () ; 

try { Thread. sleep(100) ; } 
catch (InterruptedException e) { } 
if (uxl == 0) uxl = xpos; 

} 

for (xpos = 105; xpos > 5; xpos -=4) { 
uxl = xpos; 
repaint () ; 

try { Thread. sleep(100) ; } 
catch (InterruptedException e) { } 
if (ux2 == 0) ux2 = xpos + 90; 

> 

} 

} 

public void update (Graphics g) { 

g.clipRect(ux1 , 5, ux2 - uxl, 95); 
paint (g) ; 

} 

public void paint (Graphics g) { 

// Draw background 
g.setColor(Color. black) ; 
g.fillRect(0, 0,100, 100) ; 
g.setColor(Color. white) ; 
g.fillRect(101 ,0,100,100) ; 

// Draw checker 
g . setColor (Color . red) ; 
g.fillOval(xpos,5,90,90) ; 

// reset the drawing area 
uxl = ux2 = 0; 
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Summary 

Congratulationson getting through Day lOIThisdaywasa bit rough; you’ve learned a lot, and 
it all might seem overwhelming. You learned about a plethora of methodsto use and override: 
starto, stopo, paint 0, repainto, runf), and updateo— and you gotasolid foundation in 
creating and using threads. 

After today, you’re over the worst hurdles in terms of understanding applets. Other than 
handling bitmap images, which you’ll learn about tomorrow, you now have the basic 
background to create just about any animation you want in Java. 

Q&A 

Q Why all the indirection with paint and repaint and update and all that? Why not 
have a simple paint method that just puts stuff on the screen when you want it 
there? 

A TheJavaAWT toolkit enables you to nest drawable surfaces within other drawable 
surfaces. W hen a paint takes place, all the parts of the system are redrawn, starting 
from the outermost surface and moving downward into the most nested one. Because 
the drawing of your applet takes place at the same time everything else is drawn, your 
applet doesn't get any special treatment. Your applet will be painted when everything 
else is painted. Although with this system you sacrifice some of the immediacy of 
instant painting, it enables your applet to co-exist with the rest of the system more 
cleanly. 

Q Are J ava threads like threads on other systems? 

A J ava threads have been influenced by other thread systems, and if you’re used to 
working with threads, many of the concepts in J ava threads will be very familiar to 
you. You learned the basics today; you’ll learn more next week on Day 17. 

Q W hen an applet uses threads, I just have to tell the thread to start and it starts, 
and tell it to stop and it stops? T hat's it? I don't have to test anything in my loops 
or keep track of its state? I s just stops? 

A It just stops. When you put your applet into a thread, Java can control the execution 
of your applet much more readily. By causing the thread to stop, your applet just 
stops running, and then resumes when the thread starts u p again. Yes, it’sall auto- 
matic. N eat, isn't it? 
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Q The Swirling C olors applet seems to display only five or six colors. W hat's going 
on here? 



A This is the same problem that you ran into yesterday wherein, on some systems, there 
might not be enough colors to be able to display all of them reliably. If you’re running 
into this problem, other than upgrading your hardware, you might try quitting other 
applications running on your system that use color. Other browsers or color tools in 
particular might be hogging colors that J ava wants to be able to use. 

Q Even with the changes you made, the C heckers applet still flickers. 

A And, unfortunately, it will continue to do so. Reducing the size of the drawing area by 
using clipping does significantly reduce the flickering, but it doesn’t stop it entirely. 
For many applets, using either of the methods described today may be enough to 
reduce animation flicker to the point where your applet works right. T o get totally 
flicker-free animation, you’ll use a technique called double-buffering, which you’ll 
learn about tomorrow. 
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More Animation, 
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by Laura Lemay 




More Animation, Images, and Sound 



Animations are fun and easy to do in Java, but there’s only so much you can do with the built- 
in Java methods for lines and fonts and colors. For really interesting animations, you have to 
provideyourown imagesforeach frameof the animation— and having sounds is nice, as well. 
T oday, you’ll do more with animations, incorporating images and sounds into Java applets. 

Specifically, you’ll explore the following topics: 

fl Using images— getting them from the server, loading them into Java, and displaying 
them in your applet 

Z Creating animations by using images, including an extensive example 

□ Using sounds- getting them and playing them at the appropriate times 

□ Sun’s Animator applet- an easy way to organize animations and sounds in Java 

□ D ouble-buffering— hardcore flicker avoidance 

Retrieving and Using Images 

Basic image handling in Java is easy. The image class in java, awt provides abstract methods to 
represent common image behavior, and special methods defined in Applet and Graphics give 
you everythingyou need to load and display images in your applet as easilyasdrawingarectangle. 

I n this section, you’ll learn about how to get and draw images in your J ava applets. 

Getting Images 

T o display an image in your applet, you first must load that image over the net into your Java 
program. I mages are stored as separate files from your J ava class files, so you have to tell J ava 
whereto find them. 

The Applet class provides a method called getimage, which loads an image and automatically 
creates an instance of the image class for you. To use it, all you have to do is import the 
java, awt . image class, and then givegetimage theU RL of theimageyou want to load. T here are 
two ways of doing the latter step: 

Z The getimage method with a single argument (an object of type URL) retrieves the 
image at that URL. 

Z The getimage method with two arguments: the base URL (also auRL object) and a 
string representing the path or filename of the actual image (relative to the base). 

Although thefirst way may seem easier (just plug in theU RL asauRL object), thesecond ismore 
flexible. Remember, becauseyou’recompilingjava files, if you indudea hard-coded U RL of an 
image and then move your files around to adifferent location, you have to recompile all your 
Java files. 
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The latter form, therefore, isusually theoneto use.TheA PP iet class also provides two methods 
that will help with the base U RL argument to getimage: 

□ T he getDocumentBase ( ) method returns a url object representing the directory of the 
HTML file that contains this applet. So, for example, if the H T M L fileislocated at 

htt P : / /www. my server, com/ htmlf iles/ javahtml/, getDocumentBase returns 3 U RL 

pointing to that path. 

□ T he getcodeBase ( ) method returns a string representing the directory in which this 
applet is contained— which may or may not be the same directory astheHTM L file, 
depending on whether the codebase attribute in <applet> is set or not. 

Whether you use getDocumentBase () or getcodebase( ) depends on whether your images are 
relative to your HTM L filesor relative to yourj ava classfiles. Use whichever oneapplies better 
to your situation. N otethat either of these methods is more flexible than hard-coding a U RL 
or pathname into the getimage method; using either getDocumentBase or getcodeBase enables 
you to move your HTM L files and applets around and Java can still find your images. 

H ereareafewexamplesof getimage, to giveyou an ideaof how to useit.Thisfirst call togetimage 
retrieves the file at that specific URL ("htt P ://www. server.com/files/image. gif"). If any part 
of that U RL changes, you haveto recompileyourj ava applet to takethenew path into account: 

Image img = getlmage( 

new URL( “htt P : / /www. server.com/files/image.gif 11 ) ) ; 

I n thefollowing form of getimage, theimage.gif fileisin the same directory astheHTM L files 
that refer to this applet: 

Image img = getImage(getDocumentBase( ) , "image.gif") 

I n this similar form, the file image.gif isin the same directory as the applet itself: 

Image img = getImage(getCodeBase( ) , "image.gif") 

Ifyou havelots of image files, it’scommontoputthem intotheirown subdirectory. Thisform 
of getimage looks for the file image.gif in the directory images, which, in turn, isin the same 
directory as the J ava applet: 

Image img = getImage(getCodeBase( ) , "images/image. gif ") 

If Java can't find thefileyou’veindicated, getimage returns nun. Your program will continue 
to run— you just won’t see that image on your screen when you try to draw it. 
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Note: Currently, Java supports images in the GIF and JPEG formats. Other image 
formats may be available later; however, for now, your images should be in either 
GIF orJPEG. 
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Drawing Images 

All that stuff with getimage does nothing except go off and retrieve an image and stuff it into 
an instance of the image class. Now that you have an image, you have to do something with it. 

T he most likely thing you’re going to want to do is display it as you would a rectangleor a text 
string. The Graphics class provides two methods to do just that, both called drawimage. 

T hefirst version of drawimage takes four arguments: the image to display, thex and y positions 
of the top left corner, and this: 

void paint () { 

g. drawimage (img, 10, 10, this); 

> 

Thisfirst form does what you would expect it to: it draws the image in its original dimensions 
with the top left corner at the given x and y positions. Listing 11.1 shows the code for a very 
simple applet that loads in an image called ladybug.gif and displays it. Figure 11.1 shows the 
obvious result. 




■ The second form of drawimage takes six arguments: the image to draw, the x and y 
[9S coordinates, a width and height of the image bounding box, and this. If the width and 
height arguments for the bounding box are smaller or larger than the actual image, the 
image is automatically scaled to fit. U sing those extra arguments enables you to squeeze and 
expand imagesinto whatever space you need them to fit in (keep in mind, however, that there 
may be some image degradation from scaling it smaller or larger than its intended size). 

One helpful hintfor scaling imagesisto find out thesizeof theactual image that you’veloaded, 
so you can then scale it to a specific percentage and avoid distortion in either direction. T wo 
methodsdefined for the image class enableyou do this: getwidth( ) and getHeighto. Both take 
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a singleargument, an instanceof imageobserver, which isused to track theloading of theimage 
(more about this later). M ost of the time, you can use just this as an argument to either 

getWidth() Or getHeightQ. 



Figure 11.1. 

T he Lady bug image 




If you stored theladybug imagein a variable called bugimg, for example, this line returns the 
width of that image, in pixels: 



theWidth = bugimg.getWidth(this) ; 



Listing 11.2 shows another use of theladybug image, thistimescaled several times to different 
sizes (Figure 11.2 shows the result). 
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Listing 11.2. More Ladybugs, scaled. 
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import java.awt. Graphics; 
import java.awt. Image; 

public class LadyBug2 extends java. applet. Applet { 
Image bugimg; 

public void init() { 

bugimg = getlmage(getCodeBase() , 

" images/ladybug.gif ") ; 

> 

public void paint (Graphics g) { 

int iwidth = bugimg. getWidth(this) ; 
int iheight = bugimg. getHeight(this) ; 
int xpos = 10; 

// 25 % 



continues 
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Listing 11.2. continued 

19: g.drawImage(bugimg,xpos, 10, 

20: iwidth / 4, iheight / 4, this); 

21: 

22: // 50 % 

23: xpos += (iwidth / 4) + 10; 

24: g.drawlmage(bugimg, xpos , 10, 

25: iwidth / 2, iheight / 2, this); 

26: 

27 : / / 1 00% 

28: xpos += (iwidth / 2) + 10; 

29: g.drawlmage (bugimg, xpos, 10, this); 

30: 

31: // 150% x, 25% y 

32: g.drawlmage (bugimg, 10, iheight + 30, 

33: (int) (iwidth * 1.5), iheight / 4, this); 

34: } 

35: } 



Figure 11.2. 

The second Ladybug applet. 




I’ve been steadfastly ignoring mentioning that last argument to drawimage: the mysterious 
this, which also appears as an argument to getwidtho and getHeighto. Why is this 
argument used? Its official useisto passin an object that functions as an I mageO bserver 
(that is, an object that implements the I mageO bserver interface). I mage observers enable you 
to watch the progress of how far along an image is in the loading process and to makedecisions 
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when the image is only fully or partially loaded. T he Applet class, which your applet inherits 
from, contains default behavior for watching for images that should work in the majority of 
cases- hence, the this argument to drawimageo, getwidtuo, and getHeighto. The only 
reason you’ll want to use an alternate argument in its place is if you are tracking lots of images 
loading synchronously. Seethe java. awt. image, imageobserver class for moredetails. 

Modifying I mages 

I n addition to the basics and handling images described in this section, the javaawt.image 
packageprovidesmoredasses and interfacesthatenableyou to modify images and their internal 
colors, orto create bitmap images by hand. M ost of thesedasses require background knowledge 
in image processing, including a good grasp of color models and bitwise operations. All these 
things are outside the scope of an introductory book onjava, butifyou have this background 
(or you're interested in trying it out), thedassesin javaawt.image will be helpful to you. Take 
a look at the example codefor creating and using images that comeswiththejavadevdopment 
kit for examples of how to use the image classes. 

C r eating Animation U sing I mages 

Creating animationsby using imagesismuchthesameas creating images by using fonts, colors, 
or shapes- you use the same methods, the same procedures for painting, repainting, and 
reducing flicker that you learned about yesterday. The only difference is that you haveastack 
of images to flip through rather than a set of painting methods. 

P robably the best way to show you how to use i mages for ani mati on is si mply to wal k through 
an example. H ere's an extensive one of an animation of a small cat called N eko. 

An Example: Neko 

N eko was a small M acintosh animation/game written and drawn by Kenji Gotoh in 1989. 
"N eko" isj apanesefor"cat,”andtheanimation isofasmall kitten that chases themouse pointer 
around the screen, sleeps, scratches, and generally acts cute. The N eko program has since been 
ported to just about every possible platform, aswdl as rewritten as a popular screensaver. 

For this example, you’ll implement a small animation based on the original Neko graphics. 
Because the original N eko the cat was autonomous (it could "sense” the edges of the window 
and turn and run in adifferent direction), thisapplet merely causes N eko to run in from theleft 
sideof the screen, stop in the middle, yawn, scratch its ear, sleep a little, and then run off to the 
right. 
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Note: T his is by far the largest of the applets discussed in this book, and if I either 
print it here and then describe it, or build it up line by line, you’ll be here for days. 
Instead, I’m going to describe the parts of this applet independently, and I’m going 
to leave out the basics- the stuff you learned yesterday about starting and stopping 
threads, what the runo method does, and so on. All the code is printed later today 
so that you can put it all together. 



Before you begin writing Java code to construct an animation, you should have all theimages 
that form theanimation itself. For this version of N eko there arenineof them (the original has 
36), as shown in Figure 11.3. 



Figure 11.3. 

The images for weko. 
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I 've stored these images in a subdirectory of my applet directory called, appropriately, images. 
Where you store your images isn’t all the important, but you should take note of where you’ve 
put them because you’ll need that information 

N ow, onto the applet. The basic idea of animation by using images is that you have a set of 
images, and you display them one at a time, rapidly, so they give the appearance of movement. 
The easiest way to managethisinjavaisto store the images in an array of dassimage, and then 
to have a special variable that stores a reference to the current image. 



T echnical N ote: T he j ava. utii class contains a class (Hasmabie) that implements 
a hash table. For large amounts of images, a hash table is faster to find and retrieve 
images from than an array is. Because you have a relatively small amount of images 
here, and because arrays are easier to deal with, I’ll use an array here. 



For the N eko applet, you’ll include instance variablesto implement both these things: an array 
to hold the images called nekopics, and a variable of type image to hold the current image: 

Image nekopics[] = new lmage[9]; 

Image currentimg; 

Because you’ll need to pass the position of the current image around between themethodsin 
this applet, you’ll also need to keep track of the current x and y positions. They stays constant 
for this particular applet, but the x may vary, let's add two instance variables for those two 
positions: 
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int xpos; 
int ypos = 50; 



N ow, onto thebody of theapplet. D uringtheapplet'sinitialization, you’ll read in all theimages 
and store them in thenekopics array. This is the sort of operation that works especially well in 
an inito method. 

Given that you have nine images with ninedifferent filenames, you could do a separate call to 
getimage for each one. You can save at least a little typing, however, by creating an array of the 
file names (nekosrc, an array of strings) and then just using ator loop to iterate over each one. 
H ere’s the imto method for the N eko applet that loads al I the i mages i nto the nekopics array: 

public void init() { 

String nekosrc[] = { "right1.gif", "right2.gif", 

"stop.gif", "yawn.gif", "scratch1.gif", 

" scratch2 .gif ", " sleepl . gif " , " sleep2 . gif " , 

“awake.gif" }; 

for (int i=0; i < nekopics. length; i++) { 
nekopics[i] = getImage(getCodeBase( ) , 

“images/" + nekosrc[i]); 

} 

> 

N ote here in the cal I to get image that the directory these images are stored in isincluded aspart 
of the path. 

W ith the images loaded, the next step is to start animating the bits of the applet. You do this 
inside the applet’s thread's run o method. I n this applet, Neko does five main things: 

□ tuns in from the left side of the screen 
JD Stops in the middle and yawns 
D Scratches four times 
p Sleeps 

jp I V akes up and runs off to the right side of the screen 

Because you could animate this applet by merely painting the right image to thescreen at the 
right time, it makes more sense to write this applet so that many of N eko's activities are 
containedin individual methods. Thisway, you can reuse some of the activitiesftheanimation 
of N eko running, in particular) if you want N eko to do things in a different order. 

Let's start by creating a method to make Neko run. Because you’re going to be using this one 
twice, making it generic is a good plan. Let’s create the nekorun method, which takes two 
arguments: thex position to start, and thex position to end. N eko then runsbetween those two 
positions (the y remains constant). 

There are two images that represent N eko running; so, to create the running effect, you need 
to alternate between those two images(stored in positions 0 and 1 of the image array), aswell 
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as move them across the screen. The moving part isasimpletor loop between the start and 
end arguments, setting the global x position to the current loop value. Swapping the images 
means merely testing to see which one is active at any turn of the loop and assigning the other 
one to the current image. Finally, at each new frame, you’ll call repaint and sleep for a bit. 

Actually, given that during this animation there will be a lot of sleeping of various intervals, it 
makes sense to create a method that does the sleeping for the appropriate time interval. Call it 
pause — here’s its definition: 

void pause(int time) { 

try { Thread. sleep(time) ; } 
catch (InterruptedException e) { } 

> 

Back to thenekorun method. To summarize, nekorun iteratesfrom the start position to theend 
position. For each turn of the loop, it sets the current x position, setscurrentimg to the right 
animation frame, calls repaint, and pauses. Got it? FI ere’sthe definition of nekorun: 

void nekorun(int start, int end) { 

for (int i = start; i < end; i+=10) { 
this.xpos = i; 

// swap images 

if (currentimg == nekopics[0]) 
currentimg = nekopics[1]; 
else if (currentimg == nekopics[1]) 
currentimg = nekopics[0]; 
repaint () ; 
pause(l50) ; 

} 

> 

N otethat in that second lineyou increment the loop by ten pixels. W hy ten pixels, and not, say, 
five or eight? The answer is determined mostly through trial and error to see what looks right. 
T en seems to work best for the animation. When you write your own animations, you have to 
play with both the distances and the sleep times until you get an animation you like. 

Speaking of repaint, let’s cover the paint o method, which paints each frame. FI erethepamt 
method istrivi ally simple; all paint isresponsiblefor ispai nting thecurrent imageat thecurrent 
x and y positions. All that information isstored in global variables, so the paint method hasonly 
a single line in it: 

public void paint (Graphics g) { 

g.drawlmagefcurrentimg, xpos, ypos, this); 

> 
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Now let’s back up to the runo method, where the main processing of this animation is 
happening. You’ve created the nekorun method; in run you’ll call that method with the 
appropriate values to makeN eko run from the right edge of the screen to the center: 



// run from one side of the screen to the middle 
nekorun(0, this. size() .width / 2); 

Thesecond major thing N eko doesin thisanimation isstop and yawn. You haveasingleframe 
for each of these things (in positions 2 and 3 in the array), so you don’t really need a separate 
method for them. All you need to do isset theappropriateimage, call repaint o, and pausefor 
the right amount of time. This example pauses for a second each time for both stopping and 
yawning— again, using trial and error. H ere’sthecode: 

// stop and pause 
currentimg = nekopics[2]; 
repaint () ; 
pause(lO00) ; 

// yawn 

currentimg = nekopics[3]; 
repaint () ; 
pause(l000) ; 

Let’s move on to thethird part of the animation: scratching. There’sno horizontal for this part 
of the animation. You alternate between the two scratching images(stored in positions 4 and 
5 of the image array). Because scratching is a distinct action, however, let's create a separate 
method for it. 

Thenekoscratch method takes a single argument: the number of times to scratch. With that 
argument, you can iterate, and then, insidetheloop, alternatebetweenthetwo scratching images 
and repaint each time: 

void nekoscratch(int numtimes) { 

for (int i = numtimes; i > 0; i--) { 
currentimg = nekopics[4]; 
repaint () ; 
pause(l50) ; 

currentimg = nekopics[5]; 
repaint () ; 
pause(l50) ; 



I nside the run method, you can then call nekoscratch with an argument of four: 

// scratch four times 
nekoscratch(4) ; 

Onward! After scratching, N eko sleeps. Again, you have two imagesfor sleeping (in positions 
6 and 7 of the array), which you’ll alternate a certain number of times. H ere’s the nekosieep 
method, which takes a single number argument, and animates for that many "turns": 

void nekosleep(int numtimes) { 

for (int i = numtimes; i > 0; i--) { 
currentimg = nekopics[6]; 
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repaint () ; 
pause(250) ; 

currentimg = nekopics[7]; 
repaint () ; 
pause(250) ; 

} 

> 

Call nekosieep in theruno method like this: 

// sleep for 5 "turns" 
nekosleep(5) ; 

Finally, to finish off theapplet, N eko wakes up and runsoffto the right sideof the screen, wake 
up isyour last imagein thearray (position eight), and you can reusethenekorun method to finish: 

// wake up and run off 
currentimg = nekopics[8]; 
repaint () ; 
pause(500) ; 

nekorun(xpos, this. size() .width + 10); 

There’sonemorething left to do to finish theapplet. Theimagesfortheanimation all havewhite 
backgrounds. D rawing those images on the default applet background (a medium grey) means 
an unsightly white box around each image. To get around the problem, merely set the applet's 
background to white at the start of theruno method: 

setBackground(Color. white) ; 

Got all that?T here'sa lot of code in this applet, and a lot of individual methodsto accomplish 
a rather simple animation, but it’s not all that complicated. T he heart of it, as in the heart of all 
Java animations, isto set up theframeand then call repaint o to enablethescreen to bedrawn. 

N otethat you don’t do anything to reduce theamount of flicker in thisapplet. 1 1 turnsout that 
theimagesaresm all enough, and thed rawing area also small enough, that flicker isnotaproblem 
forthisapplet. It’salwaysagood ideato writeyour animationsto do thesimplest thingfirst, and 
then add behavior to make them run cleaner. 

To finish up this section, Listing 11.3 shows the complete code for the N eko applet. 



Listing 11.3. The final Neko applet. 

36: import j ava . awt .Graphics; 

37: import j ava . awt . Image; 

38: import j ava . awt .Color; 

39: 

40: public class Neko extends java. applet. Applet 

41 : implements Runnable { 

42: 

43: Image nekopicsj] = new Image[9]; 

44: Image currentimg; 

45: Thread runner; 

46: int xpos; 
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47 

48 

49 

50 

51 

52 

53 

54 

55 

56 

57 

58 

59 

60 
61 
62 

63 

64 

65 

66 
67 

69 

70 

71 

72 

73 

74 

75 

76 

77 

78 

79 

80 



int ypos = 50; 
public void init() { 

String nekosrc[] = { "right1.gif", "right2.gif", 
"stop.gif", "yawn.gif", "scratch1.gif", 
"scratch2.gif" , “sleepl . gif" , "sleep2.gif" , 
"awake.gif” }; 

for (int i=0; i < nekopics. length; i++) { 
nekopics[i] = getImage(getCodeBase( ) , 

"images/" + nekosrc[i]); 



public void start () { 

if (runner == null) { 

runner = new Thread(this) ; 
runner. start() ; 

> 

> 

public void stop() { 

if (runner != null) { 
runner. stop() ; 
runner = null; 

> 

> 

public void run() { 

setBackground (Color. white) ; 

// run from one side of the screen to the middle 
nekorun(0, this. size() .width / 2); 
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// stop and pause 
currentimg = nekopics[2]; 
repaint () ; 
pause(l000) ; 



86: 

87: 

89: 
90: 
91 : 
92: 
93: 
94: 
95: 
96: 
97: 
98: 
99: 
100: 
101: 



// yawn 

currentimg = nekopics[3]; 
repaint ( ) ; 
pause(l000) ; 

// scratch four times 
nekoscratch(4) ; 

// sleep for 5 "turns" 
nekosleep(5) ; 

// wake up and run off 
currentimg = nekopics[8]; 
repaint () ; 
pause(500) ; 

nekorun(xpos, this. size() .width + 10); 



continues 
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Listing 11.3. continued 

102: } 

103: 

104: void nekorun(int start, int end) { 

105: for (int i = start; i < end; i+=10) { 

106: this.xpos = i; 

107: // swap images 

108: if (currentimg == nekopics[0]) 

109: currentimg = nekopics[1]; 

110: else if (currentimg == nekopics[1]) 

111: currentimg = nekopics[0]; 

112: else currentimg = nekopics[0]; 

113: 

114: repaint(); 

115: pause(150); 

116: } 

117: } 

118: 

119: void nekoscratch(int numtimes) { 

120: for (int i = numtimes; i > 0; i--) { 

121: currentimg = nekopics[4]; 

122: repaint (); 

123: pause(150); 

124: currentimg = nekopics[5]; 

125: repaint (); 

126: pause(150); 

127: } 

128: } 

129: 

130: void nekosleep(int numtimes) { 

131: for (int i = numtimes; i > 0; i--) { 

132: currentimg = nekopics[6]; 

133: repaint (); 

134: pause(250); 

135: currentimg = nekopics[7]; 

136: repaint (); 

137: pause(250); 

138: } 

139: 

140: void pause(int time) { 

141: try { Thread . sleep (time) ; } 

142: catch (InterruptedException e) { } 

143: } 

144: 

145: public void paint (Graphics g) { 

146: g.drawlmage(currentimg, xpos, ypos, this); 

147: } 

148: } 
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Retrieving and Using Sounds 

Java has built-in support for playing sounds in conjunction with running animations or for 
soundson their own. In fact, support for sound, I ike support for images, is built into theAppiet 
and awt classes, so using sound in your Java applets is as easy as loading and using images. 

Currently, the only sound format that Java supportsisSun’sAU format, sometimes called pi- 
law format. AU filestend to be smaller than sound files in other formats, butthesound quality 
is not very good. If you’re especially concerned with sound quality, you may want your sound 
clipsto bereferencesinthetraditionalHTM L way (aslinksto external files) ratherthan included 
in a Java applet. 

Thesimplestwayto retrieve and playasound isthrough thepiayo method, part of the Applet 
class and thereforeavailableto you in yourapplets. Thepiayo method issirnilartothegetimage 
method i n that it takes one of two forms: 

□ piay with one argument, auRL object, loads and plays the given audio clip at that 
URL. 

□ piay < ) with two arguments, oneabaseuRL and one a pathname, loads and plays that 
audio file. The first argument can most usefully be either a call to getDocumentBaseo 
Or getCodeBase(). 

For example, the following line of code retrieves and plays the sound meow.au, which is 
contained in theaudio directory. Theaudio directory, in turn, islocated in the same directory 
as this applet: 

play(getCodeBase( ) , "audio/meow. au“ ) ; 

The piay method retrieves and plays the given sound as soon as possible after it is called. If it 
can’t find the sound, you won’t get an error; you just won’t get any audio when you expect it. 

If you want to playasound repeatedly, start and stop the sound clip, or run the clip as a loop 
(play it over and over), thingsareslightly morecomplicated — but not much moreso. In thiscase, 
you use the applet method getAudiociipo to load thesound clip into an instance of the class 
Audiocup (part of java.applet— don't forget to import it) and then operate directly on that 
Audiocup object. 

Suppose, for example, that you have a sound loop that you want to play in the background of 
your applet. In your initialization code, you can use this line to get the audio clip: 

AudioClip clip = getAudioClip(getCodeBase() , 

"audio/loop.au" ) ; 

Then, to play the clip once, use the piay method: 



clip. play () ; 
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T o stop a currently playing sound clip, use the stopo method: 

clip.stopO ; 

T o loop the clip (play it repeatedly), usetheioopo method: 

clip. loop () ; 

If thegetAudiociip method can’t find thesound you indicate, or can't load it for any reason, 
theAudiociipvariableissettonuii.lt’sagoodideatotestforthiscaseinyourcodebeforetrying 
to play theaudio clip— , because trying to call thepiayo, stopo, and loopo methodsonanuii 
object will result in an error (actually, an exception). 

In your applet, you can play as many audio clips as you need; all the sounds you use play 
concurrently as your applet executes. 

Notethatifyou usea background sound- asound clip that loops repeatedly- that sound clip 
will not stop playing automatically when you suspend theapplet'sthread. T hismeansthat even 
if your reader moves to another page, thefirst applet'ssoundswill continueto play. You can fix 
this problem by stopping the applet's background sound in your stopo method: 

public void stop() { 

if (runner != null) { 
if (bgsound!= null) 
bgsound. stop() ; 
runner. stop() ; 
runner = null; 

> 

> 

Listing 11.4 shows a simple framework for an applet that plays two sounds: the first, a 
background sound called loop.au, playsrepeatedly.Thesecond,ahorn honking (beep.au) plays 
every five seconds. (I won’t bother givingyou a picture of thisapplet, becauseit doesn't actually 
display anything other than a simple string to the screen). 



Listing 11.4. The AudioLoop applet. 

1: import java.awt. Graphics; 

2: import java. applet. AudioClip; 

3: 

4: public class AudioLoop extends java. applet. Applet 
5: implements Runnable { 

6: 

7: AudioClip bgsound; 

8: AudioClip beep; 

9: Thread runner; 

10: 

11: public void start () { 

12: if (runner == null) { 

13: runner = new Thread(this) ; 

14: runner. start () ; 
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15: > 

16: > 

17: 

18: public void stop() { 

19: if (runner != null) { 

20: if (bgsound != null) bgsound.stop() ; 

21: runner. stop() ; 

22: runner = null; 

23: > 

24: > 

25: 

26: public void init() { 

27: bgsound = getAudioClip(getCodeBase() , "audio/loop. au" ) ; 

28: beep = getAudioClip(getCodeBase() , "audio/beep. au") ; 

29: > 

30: 

31: public void run() { 

32: if (bgsound != null) bgsound. loop() ; 

33: while (runner != null) { 

34: try { Thread . sleep(5000) ; } 

35: catch (InterruptedException e) { > 

36: if (bgsound != null) beep.play(); 

37: } 

38: } 

39: 

40: public void paint (Graphics g) { 

41: g. drawstring ("Playing Sounds....", 10, 10); 

42: } 

43: } 



Sun's Animator Applet 

Because most Java animations have a lot of codein common, being ableto reuse all that code 
asmuch aspossiblemakescreatinganimationswith images and soundsmuch easier, particular 
forj ava developers who aren't asgood at theprogramming sideof J ava. For just thisreason, Sun 
provides an Animator class as part of the standard J ava release. 

TheAnimator applet provides a simple, general-purpose animation interface. You compilethe 
code and create an HTML file with the appropriate parameters for the animation. Using the 
Animator applet, you can do the following: 

On Create an animation loop, that is, an animation that plays repeatedly. 

□ Add a soundtrack to the applet. 

0 Add sounds to be played at individual frames. 

J3r Indicate the speed at which the animation isto occur. 

□ Specify the order of the frames in the animation— which means that you can reuse 
frames that repeat during the course of the animation. 
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Even if you don’t intend to use Sun’s Animator code, it’s a great example of how animations 
work in$Javaand the sorts of clever tricks you can use in$a J ava applet. 

T he Animator classis part of thej ava distribution (in the demo directory), or you can find out 
more information about it at the$J ava home page, http : / / j ava . sun . com. 

More About Flicker: Double-Buffering 

Yesterday, you learned two simple ways to reduce flickering in$animations. Although you 
learned specifically about animations using drawing, flicker can also result from animations 
using images. I n addition to the$two flicker- reducing methods described yesterday, there is one 
other way to reduce flicker in an application: double-buffering. 

NEW** w ith double-buffering, you create a second surface (offscreen, so to speak), do all your 
TERM painting to that offscreen surface, and then draw the$wholesurfaceat onceonto theactual 
applet (and onto the screen) at the$end— rather than drawing to the applet's actual graphics 
surface. Because all the work actually goes on behind the$scenes, there’s no opportunity for 
interim parts of the$drawing process to appear accidentally and disrupt the smoothness of the 
animation. 

Double-buffering isn’t always the best solution. If your applet is suffering from flicker, try 
overriding update and drawing only portions of the screen first; that may solve your problem. 
Double-buffering is less efficient than regular buffering, and also takes up more memory and 
space, so if you can avoid it, makean effort to do so. In tarns of nearly eliminating animation 
flicker, howeva, double-buffaing works exceptionally well. 

C reating Applets with D ouble-B uffering 

To execute double-buffering, you need two things: an image to draw on and a graphics context 
forthatimage.Thosetwotogethamimicthe$effectoftheapplet’sdrawingsurface:the$graphics 
context (an instance of Graphics) to provide the$drawing methods, such asdrawimage and 
drawstring, and the image to hold the dots that get drawn. 

Thaearefour major st epsto adding double-buffaingto your applet. First, youroff screen image 
and graphics context need to be stored in instance variables so that you can pass them to the 
paint o method. Declare the following instance variables in your class definition: 

Image offscreenlmage; 

Graphics offscreenGraphics; 

Second, during the initialization of the$applet, you'll create arumage and a Graphics object and 
assign them to these variables (you have to wait until initialization so you know how big they’re 
going to be). T hecreateimage method givesyou an instanceof image, which you can then send 
thefoetGraphicso method in$orda to get a new graphics context for that image: 
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offscreenlmage = createlmage (this. size () .width, 
this.size() .height) ; 

off screenGraphics = offscreenlmage. getGraphics() ; 

N ow, whenever you have to draw to the screen (usually in your paint method), rather than 
drawingtopaint'sgraphics,drawtotheoffscreengraphics.Forexample,todrawanimagecalled 
img at position 10,10, use this line: 

off screenGraphics. drawlmage(img, 10, 10, this) ; 

Finally, at the end of your paint method, after all the drawing to the offscreen image is done, 
add the following line to print the offscreen buffer to the real screen: 

g.drawImage(offscreenImage, 0, 0, this); 

Of course, you most likely will wanttooverrideupdatesothatitdoesn’tclearthescreen between 
paintings: 

public void update (Graphics g) { 
paint(g) ; 

> 

Let's review those four steps: 

□ Add instance variables to hold the image and graphics contexts for the offscreen 
buffer. 

□ Create an image and a graphics context when your applet is initialized. 

d Do all your applet painting to the offscreen buffer, not the applet’s drawing surface, 
d At the end of your paint method, draw the offscreen buffer to the real screen. 

An Example: Checkers Revisited 

Yesterday’s example featured the animated moving red oval to demonstrate animation flicker 
and how to reduceit. Even with theoperationsyou did yesterday, however, theCheckers applet 
still flashed occasionally. Let’s revise that applet to include double-buffering. 

First, add the instance variables for the offscreen image and its graphics context: 

Image offscreenlmg; 

Graphics offscreenG; 

Second, add an mit method to initialize the offscreen buffer: 

public void init() { 

offscreenlmg = createlmage(this.size() .width, 
this. size () .height) ; 

offscreenG = offscreenlmg.getGraphicsO ; 

> 
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Third, modify the paint method to draw to the offscreen buffer instead of to themain graphics 
buffer: 

public void paint (Graphics g) { 

// Draw background 
of fscreenG.setColor (Color. black) ; 
offscreenG.f illRect (0,0, 100, 100) ; 
of f screenG. setColor( Color .white) ; 
of f screenG . f illRect (100,0,100,100); 

// Draw checker 

offscreenG.setColor(Color.red) ; 
of f screenG . f illOval (xpos ,5,90,90); 

g. drawl mage ( of fscreenlmg, 0,0, this) ; 

> 

Note that you’re still clipping the main graphics rectangle in the update method, as you did 
yesterday; you don’t have to change that part. The only part that is relevant is that final paint 
method wherein everything isdrawn offscreen before finally being displayed. 

Summary 

Threemajortopicswerethefocusoftoday’slesson. First, you learned aboutusingimagesinyour 
applets- locating them, loading them, and using thedrawimage method to display them, either 
at their normal size or scaled to different sizes. You also learned how to create animations using 
images. 

Secondly, you learned how to use sounds, which can beincluded in your applets any timeyou 
need them- at specific moments, orasbackgroundsoundsthat can be repeated whiletheapplet 
executes. You learned how to locate, load, and play sounds both using the piayo and the 
getAudioClipO methods. 

Finally, you learned about double-buffering, atechniquethatenablesyou virtually to eliminate 
flicker in animations, at some expense of animation efficiency and speed. Using images and 
graphics contexts, you can create an offscreen buffer to draw to, the result of which is then 
displayed to the screen at the last possible moment. 
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Q&A 

Q In the Neko program, you put the image loading into the inito method.lt 
seems to me that it might take Java a long time to load all those images, and 
because inito isn't in the main thread of the applet, there's going to be a 
distinct pause there. W hy not put the image loading at the beginning of the run( ) 
method instead? 

A There are sneaky things going on behind the scenes. Thegetimage method doesn’t 
actually load the image; in fact, it returns an image object almost instantaneously, so it 
isn’t taking up a large amount of processing time during initialization. The image data 
that getimage points to isn't actually loaded until the image is needed. This way, Java 
doesn't have to keep enormous images around in memory if the program is going to 
use only a small piece. Instead, it can just keep a reference to that data and retrieve 
what it needs later. 

Q I wrote an applet to do a background sound using the getAudiociipo and ioop<) 
methods. The sounds works great, but it won't stop. I've tried suspending the 
current thread and killing, but the sound goes on. 

A I mentioned this as a small note in the section on sounds; background sounds don’t 
run in the main thread of the applet, so if you stop the thread, the sound keeps going. 
The solution is easy— in the same method where you stop the thread, also stop the 
sound, like this: 

runner. stop( ) //stop the thread 
bgsound.stop() //also stop the sound 

Q If I use double-buffering, do I still have to clip to a small region of the screen? 
Because double-buffering eliminates flicker, it seems easier to draw the whole 
frame every time. 

A Easier, yes, but less efficient. Drawing only part of the screen not only reduces flicker, 
it also limits the amount of work your applet has to do in the paint o method. The 
faster the paint o method works, the faster and smoother your animation will run. 
Using clip regions and drawing only what is necessary is a good practice to follow in 
general— not just if you have a problem with flicker. 
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J ava events are part of theJavaAWT (Abstract Windowing Toolkit) package. An event is the 
way that the AWT communicates to you, as the programmer, and to other Java AWT 
components that somethi ng has happened. T hat something can be input from the user (mouse 
movements or clicks, keypresses), changes in the system environment (a window opening or 
closing, the window being scrolled up or down), or a host of other things that might, in some 
way, be interesting to the operation of the program. 



N ote: J ava’s Abstract W indowing T oolkit is a package of classes that implements 
most common U I components, such as windows, buttons, menus, and so on. It is 
also specifically the AWT, and notjava, that generates and manages events. 



I n other words, whenever just about anything happensto aJavaAWT component, including 
an applet, an event isgenerated. Someeventsarehandled by theAWT or by thebrowser without 
your needing to do anything, paint < > methods, for example, are generated and handled by the 
browser— all you have to do istell theAWT what you want painted when it gets to your part 
of the window. Some events, however— for example, a mouse click inside the boundaries of 
your applet— you may need to know about. W riting your J ava programsto handlethese kinds 
of events enablesyou to get input from theuserand have your applet change its behavior based 
on that input. 

T oday, you’ll learn about managing simple events, including the following basics: 

□ Mouse clicks 

□ M ouse movements, including mouse dragging 

□ Keyboard actions 

You’ll also learn about the handieEvento method, which is the basisfor collecting, handling, 
and passing on events of all kinds from your applet to other U I components in the window or 
in your applet itself. T omorrow, you’ll learn how to combine events with theAWT to create a 
complete interface for your applet. 



Mouse Clicks 

Let's start with themost common eventyou might beinterested in: mouse clicks. M ouse-dick 
events occur when your user clicks the mouse somewhere in the body of your applet. You can 
intercept mouse clicks to do very simple things- for example, to toggle the sound on and off 
in your applet, to move to thenext slide in a presentation, or to clear the screen and start over— 
or you can use mouse clicks in conjunction with mouse movements to perform more complex 
motions inside your applet. 
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mouseDown and mousellp 

When you click the mouse once, theAWT generates two events: amouseDown event when the 
mouse button is pressed, and a mouseup event when the button is released. Why two individual 
events for a single mouse action? Because you may want to do different things for the "down” 
and the "up.” For example, look at a pull-down menu. The mouseDown extendsthemenu, and 
the mouseup selects an item (with mouseDrags between— but you’ll learn about that one later). 
If you have only one event for both actions (mouseup and mouseDown), you cannot implement 
that sort of user interaction. 

H andling mouse events in your applet is easy— all you have to do is override the right method 
definition in your applet. T hat method will be called when that particular event occurs. H ere’s 
an example of the method signature for a mouseDown event: 

public boolean mouseDown(Event evt, int x, int y) { 

} 

ThemouseDowno method (andthemouseupo method as well) takes three parameters: the event 
itself and the x and y coordinates where the mouseDown or mouseup event occurred. 

Theevent argumentisan instance of the class Event. All system events generate an instance of 
theEvent class, which containsinformation about whereand when theeventtook place, thekind 
of event it is, and other information that you might want to know about thisevent. Sometimes 
having a handle to that event object is useful, as you’ll discover later on in this section. 

The x and the y coordinates of the event, as passed in through the x and y arguments, are 
parti cularlyniceto know becauseyou can usethem to determinepreciselywherethemouse click 
took place. 

For example, here's a simple method that prints out information about a mouseDown when it 
occurs: 

public boolean mouseDown(Event evt, int x, int y) { 

System. out. println( "Mouse down at " + x + + y); 

return true; 

} 

By including this method in your applet, every time your user clicks the mouse inside your 
applet, this message will get printed. 

N ote that this method, unlike the other system methods you’ve studied this far, returns a 
boolean value instead of not returning anything (void). T his will become important tomorrow 
when you create user interfaces and then manage input to these interfaces; having an event 
handler return true or false determines whether a given U I component can intercept an event 
or whether it needs to pass it on to the endosi ng component. T he general rule is that if your 
method dealswith theevent, it should return true, which forthefocusof today’slesson isalmost 
always the case. 
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The second half of the mouse click isthemouseupo method, which is called when the mouse 
button is released. To handle a mouseup event, add the mouseup o method to your applet. 

mouseUp () looks jUSt HkemouseDown(): 

public boolean mouseUp(Event evt, int x, int y) { 



An Example: Spots 

In this section, you’ll create an example of an applet that uses mouse events- mouseDown events 
in particular. T heSpots applet startswith ablank screen and then sits and waits. W hen you click 
themouseon that screen, abluedotisdrawn. You canplaceupto tendotson thescreen. Figure 
12.1 shows the Spots applet. 



Figure 12.1. 

TheSpotsapplet. 




Let's start from the beginning and build this applet, starting from the initial class definition: 

import java.awt. Graphics; 
import java.awt. Color; 
import java.awt. Event; 

public class Spots extends java. applet. Applet { 
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final int MAXSPOTS =10; 

int xspots [ ] = new int [ MAXSPOTS ] ; 



int yspots[] = new int[MAXSPOTS] ; 
int currspots = 0; 



T his class uses three other awt classes: Graphics, color, and Event. T hat last class, Event, needs 
to be imported in any applets that use events. The class has four instance variables: a constant 
to determine the maximum number of spots that can be drawn, two arrays to store the x and 
y coordinates of the spots that have already been drawn, and an integer to keep track of the 
number of the current spot. 



N ote: T his class doesn’t include the implements Runnable words in its definition. 
Asyou’ll see later on as you build this applet, it also doesn’t havearuno method. 
W hy not? Because it doesn’t actually do anything on its own— all it does is wait for 
input and then do stuff when input happens. T here’s no need for threads if your 
applet isn’t actively doing something all the time. 



Let's start with themito method, which has one line, to set the background to white: 

public void init() { 

setBackground(Color. white) ; 

> 

Set the background here, instead of in painto, because paint o iscalled repeatedly each time 
a new spot is added. Because you really need to set the background only once, putting it in the 
painto method unnecessarily slowsdown that method. Putting it here is a much better idea. 

The main action of this applet occurs on themouseDowno method, so let's add that one now: 

public boolean mouseDown( Event evt, int x, int y) { 
if (currspots < MAXSPOTS) 
addspot(x,y) ; 

else System. out. println("Too many spots."); 
return true; 

> 

W hen the mouse click occurs, the mouseDown < ) method tests to see whether there are less than 
ten spots. If so, it calls theaddspoto method (which you’ll write soon). If not, it just prints an 
error message. Finally, it returns true, because all the event methods have to return a boolean 
value (usually true). 

What does addspoto do? It adds the coordinates of the spot to the arrays that store the 
coordinates, increments the currspots variable, and then calls repamto: 

void addspot(int x,int y) { 

xspots[currspots] = x; 
yspots[currspots] = y; 
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currspots++; 
repaint () ; 

} 

You may be wondering why you haveto keep track of all the past spots in addition to thecurrent 
spot. The reason isbecauseof repaint o: each timeyou paint thescreen, you haveto paint all 
the old spots in addition to the newest spot. Otherwise, each timeyou painted anew spot, the 
older spots would get erased. Now, on to the paint o method: 



public void paint (Graphics g) { 
g.setColor(Color.blue) ; 
for (int i = 0 ; i < currspots; i++) { 

g.fillOval(xspots[i] -10, yspots[i] -10,20,20); 

> 

} 

I nside paint, you just loop through the spots you’ve stored in the xspots and yspots arrays, 
painting each one (actually, painting them a littleto the right and upward so that the spot is 
painted around the mouse pointer rather than below and to the right). 



That's it! That’s all you need to create an applet that handles mouse clicks. Everything else is 
handled for you. You haveto add the appropriate behavior to mouseDowno or mouseup o to 
intercept and handle that event. Listing 12.1 shows the full text for the Spots applet. 



Type 



Listing 12.1. The Spots applet. 



1: import java.awt. Graphics; 
2: import java.awt. Color; 

3: import j ava . awt . Event ; 



6 

7 

8 
9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 
27 



public class Spots extends java. applet. Applet { 

final int MAXSPOTS =10; 

int xspots[] = new int [ MAXSPOTS ] ; 
int yspots [] = new int [ MAXSPOTS ] ; 
int currspots = 0; 

public void init() { 

setBackground(Color. white) ; 



public boolean mouseDown (Event evt, int x, int y) { 
if (currspots < MAXSPOTS) 
addspot(x.y) ; 

else System. out. println("Too many spots."); 
return true; 



void addspot(int x,int y) { 
xspots[currspots] = x; 
yspots[currspots] = y; 
currspots++; 
repaint () ; 
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28: > 

29: 

30: public void paint (Graphics g) { 

31: g.setColor(Color.blue) ; 

32: for (int i = 0; i < currspots; i++) ( 

33: g .fillOval(xspots[i] -10, yspots[i] -10,20,20); 

34: } 

35: > 

36: } 



Mouse Movements 

Everytimethemouseismoved asinglepixel in any direction, a mouse move event is generated. 
T here are two mouse movement events: mouse drags, where the movement occurs with the 
mouse button pressed down, and plain mouse movements, where the mouse button isn’t 
pressed. 

T o manage mouse movement events, use the mouseDrago and mouseMoveo methods. 

mouseD rag and mouseM ove 

T hemouseDrag ( ) and mouseMoveo methods, when included in your applet code, intercept and 
handlemousemovem ent events. ThemouseMoveo method, for plain mouse pointer movements 
without the mouse button pressed, looks much like the mouse-dick methods: 

public boolean mouseMove(Event evt, int x, int y) { 



The mouseDrago method handles mouse movements made with the mouse button pressed 
down ( a com pi ete d raggi n g movement consistsof amouseDown event, aseriesof mouseDrag events 
for each pixel the mouse is moved, and a mouseup even when the button is rdeased). The 
mouseDrago method looks like this: 
public boolean mouseDrag(Event evt, int x, int y) { 



mouseE nter and mouseE xit 

Finally, there are the mouseEntero and mouseExito methods. T hese two methods are called 
when the mouse pointer entersthe applet or when it exits the applet. (In caseyou’re wondering 
why you might need to know this, it’s more useful on components of user interfaces that you 
might put inside an applet. You’ll learn more about U I tomorrow). 
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Both mouseEntero and mouseExito havesimilar signatures— threeargumentstheevent object 
and the x and y coordinates of the point where the mouse entered or exited the applet. 

public boolean mouseEnter(Event evt, int x, int y) { 



public boolean mouseExit(Event evt, int x, int y) { 



An Example: Drawing Lines 

Examples alwayshelpto makeconceptsmoreconcrete. I n thissection you’ll createan applet that 
enablesyou to draw straight linesonthescreen by dragging from thestartpoint to theendpoint. 
Figure 12.2 shows the applet at work. 




Aswith the Spots applet (on which thisapplet isbased), let’sstart with the basic definition and 
work our way through it. Listing 12.2 shows the top of the Lines applet. 



Listing 12.2. The top of the Lines applet. 
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1: import java.awt. Graphics; 
2: import java.awt. Color; 

3: import j ava . awt . Event ; 



import java.awt. Point; 

public class Lines extends java. applet. Applet { 



8 

9 

10 

11 

12 

13 

14 

15 

16 

17 

18 



final int MAXLINES = 10; 

Point starts!] = new Point[MAXLINES] ; // starting points 
Point ends[] = new Point [10]; // ending points 

Point anchor; // start of current line 
Point currentpoint; // current end of line 
int currline =0; // number of lines 

public void init() { 

setBackground(Color. white) ; 

> 



■ Compared to Spots, thisapplet added afew extra things. U nlikeSpots, which keepstrack 
(SIS of individual integercoordinates,thisonekeepstrackofpointobjects. Points represent an 
x and a y coordinate, encapsulated in a single object. To deal with points, you import the 
point class (line 4) and set up a bunch of in stance variables that hold points: 

Ip T he starts array holds points representing the starts of lines already drawn, 
jpi T he ends array holds the endpoints of those same lines, 
p anchor holds the starting point of the line currently being drawn. 

□ purrentpoint holds the current endpoint of the line currently being drawn. 

ID curriine holds the current number of lines (to make sure you don’t go over 
maxlines). 

Finally, theinito method (lines 15 through 17), asin the Spots applet, sets the background 
of the applet to white. 

The three main events this applet deals with aremouseDowno, to set the anchor point for the 
current line, mouseDrago, to animate the current line as it’s being drawn, and mouseup! ), to set 
the ending point for the new line. Given that you haveinstancevariablesto hold each of these 
values, it’s merely a matter of plugging the right variables into the right methods. H ere's 
mouseDowno, which sets the anchor point: 

public boolean mouseDown( Event evt, int x, int y) { 
anchor = new Point(x,y); 
return true; 

> 

While the mouse is being dragged to draw the line, the applet animates the line being drawn. 
Asyou draw the mouse around, the new line moves with it from the anchor point to the tip of 
the mouse. The mouseDrag event containsthe current point each time the mouse moves, so use 
that method to keep track of the current point (and to repaint for each movement so the line 
"animates”): 
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public boolean mouseDrag( Event evt, int x, int y) { 
currentpoint = new Point(x,y); 
repaint () ; 
return true; 

> 

T henewlinedoesn’t get added to thearraysof old linesuntil themousebutton isrel eased. H ere's 
mouseupo, which tests to makesureyou haven't exceeded the maxi mum number of lines before 
calling the addiineo method (described next): 

public boolean mouseUp(Event evt, int x, int y) { 
if (currline < MAXLINES) 
addline(x,y) ; 

else System. out. println("Too many lines."); 
return true; 

} 

Theaddiineo method iswhere thearraysof linesget updated and where theapplet is repainted 
to take the new line into effect: 

void addline(int x,int y) { 
starts[currline] = anchor; 
ends[currline] = new Point(x,y); 
currline++; 
currentpoint = null; 
repaint () ; 

> 

Note that in this line you also set currentpoint to nun. Why? Because the current line in 
process is over. By setting currentpoint to nun, you can test for that value in the painto 
method. 

Painting theapplet meansdrawing all theold lines stored in thestartsand en68 arrays, aswell 
as drawing the current line in process (whose en6points are in anchor and currentpoint, 
respectively). T o show the animation of the current line, draw it in blue. H ere’s the paint ( ) 
method for the Lines applet: 

public void paint (Graphics g) { 

// Draw existing lines 
for (int i = 0; i < currline; i++) { 
g.drawLine(starts[i] .x, starts[i] .y, 
en6s[i].x, en6s[i].y); 



// draw current line 
g.setColor(Color.blue) ; 
if (currentpoint != null) 

g. drawLine( anchor. x, anchor. y, 

currentpoint. x, currentpoint. y) ; 
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In paint, when you’redrawingthecurrent line, you test first to seewhethercumentpointisnull. 
If it is, theapplet isn’t in the middleof drawing a line, so there’s no reason to try drawing a line 



that doesn’t exist. By testing for currentpoint (and by setting currentpoint to null in the 
addime o method), you can paint only what you need. 



That’s it— just 60 lines of code and a few basic methods, and you have a very basic drawing 
application in your W eb browser. Listing 12.3 showsthefull text of theLines applet so that you 
can put the pieces together. 
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Listing 12.3. continued 



46: 

47: // Draw existing lines 

48: for (int i = 0; i < currline; i++) { 

49: g.drawLine(starts[i] .x, starts[i].y, 

50: ends[i].x, ends[i].y); 

51: } 

52: 

53: // draw current line 

54: g.setColor(Color.blue) ; 

55: if (currentpoint != null) 

56: g. drawLine( anchor. x, anchor. y, 

57: currentpoint. x, currentpoint. y) ; 

58: } 

59: } 



K eyboard E vents 

Keyboard events are generated whenever users press a key on thekeyboard. By using key events, 
you can get hold of the values of the keys they pressed to perform an action or merely to get 
character input from the users of your applet. 

The keyD own Method 

T o capture a keyboard event, usethekeyDowno method: 

public boolean keyDown(Event evt, int key) { 



The keys generated by keyDown events (and passed into keyDowno as the key argument) are 
integers representing ASCI I character values, which includealphanumeric characters, function 
keys, tabs, returns, and so on. To usethem as characters (for example, to print them), you need 
to cast them to characters: 

currentchar = (char)key; 

H ere's a simple example of a keyDowno method that does nothing but print the key you just 
typed in both its ASCI I and character representation: 

public boolean keyDown(Event evt, int key) { 

System. out. println( "ASCII value: " + key); 

System. out. println( "Character: " + (char)key); 
return true; 
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Default Keys 

The Event class provides a set of class variables that refer to several standard nonalphanumeric 
keys, such asthearrow keys. I f your interfaceusesthesekeys, you can providemorereadablecode 
by testingforthesenamesin your keyDowno method rather than testing for their numeric values. 
For example, to test whether the up arrow was pressed, you might use the following snippet of 
code: 

if (key == Event. UP) { 



Because the values these class variables hold are i ntegers, you also can usetheswitch statement 
to test for them. 

T able 12.1 shows the standard event class variables for various keys and the actual keys they 
represent. 

Table 12.1. Standard keys defined by the event class. 



Class Variable 


Represened Key 


Event. HOME 


TheH omekey 


Event. END 


TheEnd key 


Event. PGUP 


The Page Up key 


Event. PGDN 


The Page Down key 


Event. UP 


The up arrow 


Event. DOWN 


T he down arrow 


Event. LEFT 


The left arrow 


Event. RIGHT 


The right arrow 



An Example: Entering, Displaying, and 
Moving C haracters 

Let’s look at an applet that demonstrates keyboard events. This one enables you to type a 
character, and it displays that character in thecenter of theapplet window. You then can move 
that character around on the screen by using the arrow keys. T yping another character at any 
time changes the character as it’s currently displayed. Figure 12.3 shows an example. 
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Figure 12.3. 

T he Keysapplet. 




T hisapplet isactually lesscomplicated thanthepreviousappletsyou’veused.Thisonehasonly 
three methods: mit ( ) , keyDown o, and paint o.T he i n stan ce vari ab I es are al so simpler, because 
theonly things you need to keep track of arethexand y positionsof thecurrent character and 
the values of that character itself. H ere’sthetop of this class definition: 

import java.awt. Graphics; 
import java.awt. Event; 
import java.awt. Font; 

public class Keys extends java. applet. Applet { 

char currkey; 
int currx; 
int curry; 

Theinito method is responsible for three things: setting the background color, setting the 
applet'sfont (here, 36 point H elvetica bold), and settingthebeginningposition forthecharacter 
(the middle of the screen, minus a few points to nudge it up and to the right): 

public void init ( ) { 

currx = (this. size() .width / 2) -8; // default 

curry = (this. size() .height / 2) -16; 
setBackground (Color. white) ; 
set Font (new Font ( "Helvetica" , Font .BOLD, 36) ) ; 

} 
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Becausethisapplet'sbehavior isbased on keyboard input, thekeyDowno method iswheremost 
of the work of the applet takes place: 

public boolean keyDown(Event evt, int key) { 
switch (key) { 
case Event. DOWN: 
curry += 5; 
break; 

case Event. UP: 
curry -= 5; 
break; 

case Event. LEFT: 
currx -= 5; 
break; 

case Event. RIGHT: 
currx += 5; 
break; 

default: 

currkey = (char)key; 

} 

repaint () ; 
return true; 

} 

I n the center of the keyDownt > applet is a switch statement that tests for different key events. If 
theeventisan arrow key,theappropriatechangeismadeto the character's posi ti on . Iftheevent 
is any other key, the character itself is changed. T he method finishes up with a repaint ( ) and 
returns true. 



The paint o method here is almost trivial; just display the current character at the current 
position. H owever, notethat when the applet startsup, there’sno initial character and nothing 
to draw, so you have to take that into account. The currkey variable is initialized to 0, so you 
paint the applet only if currkey has an actual value: 



public void paint (Graphics g) { 
if (currkey != 0) { 

g.drawString(String.valueOf (currkey) , currx, curry) ; 

} 

} 



Listing 12.4 shows the complete source for the Keys applet: 



Type 



Listing 12.4. The Keys applet. 



1: import java.awt. Graphics; 
2: import java.awt. Event; 

3: import j ava . awt . Font ; 



5: public class Keys extends java. applet. Applet { 

6: 



char currkey; 
int currx; 



continues 
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Listing 12.4. continued 

9: int curry; 

10: 

11: public void init() { 

12: currx = (this. size() .width / 2) -8; // default 

13: curry = (this . size( ). height / 2) -16; 

14: 

15: setBackground(Color. white) ; 

16: setFont(new Font ( “Helvetica" , Font .BOLD, 36) ) ; 

17: } 

18: 

19: public boolean keyDown(Event evt, int key) { 

20: switch (key) { 

21: case Event. DOWN: 

22: curry += 5; 

23: break; 

24: case Event. UP: 

25: curry -= 5; 

26: break; 

27: case Event. LEFT: 

28: currx -= 5; 

29: break; 

30: case Event. RIGHT: 

31 : currx += 5; 

32: break; 

33: default: 

34: currkey = (char)key; 

35: > 

36: 

37: repaint(); 

38: return true; 

39: > 

40: 

41: public void paint (Graphics g) { 

42: if (currkey != 0) { 

43: g. drawstring (String. valueOf (currkey) , currx, curry) ; 

44: > 

45: } 

46: } 



Testing for Modifier Keys 

Shift, control, and metaaremodifier keys. They don't generate key eventsthemselves, but when 
you get an ordinary mouse or keyboard event, you can test to see whether those keys were held 
down when the event occurred. Sometimes it may be obvious— shifted alphanumeric keys 
produce different key events than unshifted ones, for example. For other events, however— 
mouse eventsin particular— you may want to handle an event with a modifier key held down 
differently from a regular version of that event. 
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T he Event class providesthree methodsfor testing whether or not a modifier key is held down: 
shittDowno, metaDowno, and controiDown(). All return boolean values based on whether that 
modifier key isindeed held down. You can use these threemethodsin any of theevent handling 
methods (mouse or keyboard) by calling them on theevent object passed into that method: 

public boolean mouseDown( Event evt, int x, int y ) { 
if (evt.shiftDown) 

// handle shift -click 
else // handle regular click 

} 

The AWT Event Handler 

Thedefaultmethodsyou'velearned about today for handling basic eventsin appletsareactually 
called by a generic event handler method called handieEvento.ThehandieEvento method is 
how the AWT generically deals with events that occur between application components and 
events based on user input. 

In the default handieEvento method, basic events are processed and themethodsyou learned 
about today are cal led. T o handleeventsotherthan thosementioned here, to change thedefault 
event handling behavior, or to create and pass around your own events, you need to override 
handieEvent in your own J ava programs. T he handieEvent( ) method looks like this: 

public boolean handieEvent (Event evt) { 

> 

To test for specific events, examine the ID instance variableof theEvent object that gets passed 
in. Theevent ID is an integer, but fortunately, theEvent class definesa whole set of event IDs 
asdassvariablesthatyou can testforinthebodyofthehandieEvent.Becausetheseclassvariables 
are integer constants, a switch statement works particularly well. For example, here’s a simple 
handieEvento method to print out debugging information about mouse events: 

public boolean handleEvent(Event evt) { 
switch (evt. id) { 
case Event. MOUSE_DOWN: 

System. out. println("MouseDown: " + 
evt.x + " , " + evt.y) ; 
return true; 
case Event. MOUSE_UP: 

System. out. println("MouseUp: " + 
evt.x + " , " + evt.y) ; 
return true; 
case Event. MOUSE_MOVE: 

System. out. println("MouseMove: “ + 
evt.x + " , " + evt.y) ; 
return true; 
case Event. MOUSE_DRAG: 

System. out. println("MouseDown: " + 
evt.x + " , " + evt.y) ; 
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return true; 
default : 

return false; 



You can test for the following keyboard events: 

□ Event . keypress is generated when a key is pressed (the same as the keyDown < ) 
method). 

□ Event, keyrelease is generated when a key is released. 

□ Event . keyaction is generated when a key action (a press and a release) occurs. 

You can test for these mouse events: 

□ Event. mouse_down is generated when the mouse button is pressed (the same as the 
mouseDown() method). 

□ Event, mousejjp is generated when the mouse button is released (the same as the 
mouseup( ) method). 

□ Event. mouse_move is generated when the mouse is moved (thesarneasthemouseMoveo 
method). 

□ Event . mouse_drag is generated when the mouse is moved with the button pressed (the 
sameasthenouseDrago method). 

□ Event ,mouse_enter is generated when the mouse enters the applet (or a component of 
that applet). You can also usethemouseEntero method. 

□ Event. mouse_exit is generated when the mouse exits the applet. You can also use the 
mouseExito method. 

I n addition to these events, the Event class has a whole suite of methods for handling U I 
components. You’ll learn more about these events tomorrow. 

N ote that if you override handieEvento in your class, none of the default event handling 
methods you learned about today will get called unless you explicitly call them in the body of 
handieEvent ( ) , so be careful if you decide to do this. 0 ne way to get around this is to test for 
theevent you’re interested in, and if that event isn’t it, to call super. handieEvento so that the 
superclass that defines handieEvento can process things. H ere’san exampleof how to do this: 

public boolean handieEvent (Event evt) { 
if (evt. id == Event. MOUSE_DOWN) { 

// process the mouse down 
return true; 

> else { 

return super. handieEvent (evt) ; 

> 
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Summary 

H andlingeventsinJava'sAbstractWindowingT oolkit (AWT ) iseasy. M ostof thetime, all you 
need to do isstick theright method in your applet code, and your applet intercepts and handles 
that method. H ere are some of the basic events you can managein thisway: 

□ M ouse clicks- mouseup o and mouseDowno methods for each part of a mouse click, 
tj M ouse movements- mouseMoveo and mouseDrago for mouse movement with the 

mouse button released and pressed, respectively, as well asmouseEntero and 
mouseExit ( ) for when the mouse enters and exits the applet area. 

□ keyDown for when a key on the keyboard is pressed. 

All events i n theAWT generatean Event object; insidethat object, you can find out information 
about the event, when it occurred, and itsx and y coordinates (if applicable). You can also test 
that event to see whether a modifier key was pressed when the event occurred, by using the 
shiftDown(), controlDown(), and metaDown() methods. 

Finally, there is the handieEvento, the "parent” of the individual event methods. The 
handieEvento method is actually what the Java system calls to manage events; the default 
implementation callsthe individual method events where necessary. To override how methods 
are managed in your applet, override handieEvent. 

Q&A 

Q I n the Spots applet, the spot coordinates are stored in arrays, which have a 
limited size. H ow can I modify this applet so that it will drawn an unlimited 
number of spots? 

A You can do one of a couple things: 

The first thing to do is test, in your addspoto method, whether the number of spots 
has exceeded maxspots. T hen create a bigger array, copy the elements of the old array 
into that bigger array (use the system, amaycopyo method to do that), and reassign 
the x and y arrays to that new, bigger array. 

The second thing to do isto usethevector class, vector, part of the java, util package, 
implements an array that is automatically growable — sort of like a linked list is in 
other languages. T he disadvantage of vector is that to put something into vector, it 
has to bean actual object. This means you’ll have to cast integers to integer objects, 
and then extract their values from integer objects to treat them as integers again. The 
vector class enables you to add and remove objects to the end of vector just as you 
can in an array (by using method calls, rather than array syntax). Check it out. 
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Q mouseDown ( ) and mouseup ( ) seem to apply to only a single mouse button. H ow can 
I determine which button on the mouse has been pressed? 

A At the moment, you can’t. AWT assumesthat you’re using only one mouse button, or 
if you have a mouse with multiple buttons, that you’re using only the left one. 
Although this provides some limitations on the kinds of actions you can perform in 
your applet, it does provide a cross- platform solution. Remember- different systems 
have different mice, so writing your applet to do something specific with the right 
mouse button isn’t a good idea if the people running your applet are using 
M acintoshesand have only one mouse button. If you really want to have different 
mouse actions perform different things, test for modifier keys in your mouseDown ( > and 
mouseup< ) methods. 

Q What's a meta key? 

A It’s popular in U nix systems, and often mapped to Alt on most keyboards. Because 
Shift and Ctrl are much more popular and widespread, it’s probably a good idea to 
base your interfaces on those modifier keys if you can. 

Q H ow do I test to see whether the Return key has been pressed? 

A Return (linefeed) is character 10; Enter (carriage return) is character 13. N otethat 
different platforms may send different keys for the actual key marked Return. In 
particular, Unix systems send linefeeds, M acintoshessend carriage returns, and DOS 
systems send both. So, to provide a cross- platform behavior, you may want to test for 
both linefeed and carriage return. 

The word from thejavateam is that a Return is a Return is a Return regardless of the 
platform. H owever, at the time of this writing, it is questionable whether or not this is 
currently true in thej ava developer’s kit. You may want to check the API documenta- 
tion fortheEvent class to see whether this has changed in theinterim. 

Q I looked at the API for the Event class, and there are many more event types 
listed there than the ones you mention today. 

A Yes. The Event class defines many different kinds of events, both for general user 
input, such as the mouse and keyboard events you learned about here, and also events 
for managing changes to the state of user interface components, such as windows and 
scroll bars. T omorrow, you’ll learn about those other events. 
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Forthepastfivedaysyou’veconcentrated on creating appletsthatdo very simplethings: display 
text, play an animation or asound, or enablevery basic interactionswith theuser. 0 nee you get 
past that point, however, you may want to start creating more complex applets that behave like 
real applications, embedded in aW eb page- appletsthat start to look likereal G U I applications 
with buttons, menus, text fields and other elements of a real application. 

It’s this sort of real work in Java applets and applications that Java’s Abstract Windowing 
T oolkit, or AWT, wasdesigned for. You’veactually been using theAWT all along, asyou might 
have guessed from the classes you've been importing. The Applet class and most of the classes 
you've been using thisweek are all integral parts of theAWT. In fact, the H otj ava browser is 
also written injavaand usestheAWT as well. 

TheAWT provides the following: 

□ A full set of U I widgets and other components, including windows, menus, buttons, 
checkboxes, text fields, scrollbars, and scrolling lists 

□ Support for U I "containers,” which can contain other embedded containers or U I 
widgets 

□ An event system for managing system and user events between and among parts of the 
AWT 

□ M echanismsfor laying out components in a way that enables platform-independent 
Ul design 

T oday, you’ll learn about how to useall thesethingsin yourj ava applets. T omorrow, you’ll learn 
about creating windows, menus, and dialogs, which enable you to pop up separate windows 
from the browser window. In addition, you can use theAWT in stand-alone applications, so 
everything you’ve I earned so far this week can still beused. Ifyoufindtheframework oftheWeb 
browser too limiting, you can takeyour AWT background and start writing full-fledged Java 
applications. 

T oday, however, you’ll continue focusing on applets. 



N ote: T his is by far the most complex lesson so far. T here’s a lot to cover and a lot 
of code to go through today, so if it starts becoming overwhelming, you might 
want to take two days (or more) for this one. 



An AWT Overview 
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The basic idea behind theAWT is that aj ava window is a set of nested components, starting 
from theoutermost window all the way down to the smallest U I component. C omponentscan 



includethingsyou can actually seeon thescreen, such aswindows, menubars, buttons, and text 
fields, and they can also indudecontainers, which in turn can contain other components. F igure 
13.1 shows how a sample page in a J ava browser might include several different components, 
all of which are managed through the AWT. 

This nesting of components within containers within other components creates a hierarchy of 
components, from thesmallest checkbox inside an applet to the overall window on thescreen. 
T he hierarchy of components determines the arrangement of items on the screen and inside 
other items, theorder in which they arepainted, and how events are passed from onecomponent 
to another. 



Figure 13.1. 

AWT components 




These are the major components you can work with in theAWT : 

□ Containers Containers are generic AWT components that can contain other compo- 
nents, including other containers. The most common form of container is the panel, 
which represents a container that can be displayed on screen. Applets are a form of 
panel (in fact, the Applet class is a subclass of the panel class). 

□ Canvases A canvas is a simple drawing surface. Although you can draw on pands(as 
you’ve been doing all along), canvases are good for painting images or other graphics 
operations. 

□ U I components These can include buttons, lists, simple popup menus, checkboxes, test 
fields, and other typical elements of a user interface. 
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Q Window construction components These include windows, frames, menubars, and 
dialogs. These are listed separately from the other Ul components because you’ll use 
these less often- particularly in applets. I n applets, the browser provides the main 
window and menubar, so you don’t have to use these. Your applet may create a new 
window, however, or you may want to write your own Java application that uses these 
components. 

T hedassesinsidethejava. awt packagearewritten and organized to mirrortheabstract structure 
of containers, components, and individual U I components. Figure 13.2 showssomeof thedass 
hierarchy that makesupthemaindassesintheAWT.Theroot of most of theAWT components 
is the class component, which provides basic display and event handling features. The classes 
container, canvas, Textcomponent, and many of the other Ul components inherit from 
component. Inheriting from the container class are objects that can contain other AWT 
components- the panel and window classes, in particular. N otethat the java. applet. Applet 
class, even though it livesin itsown package, inheritsfrom panel, so your applets are an integral 
part of the hierarchy of components in theAWT system. 



Figure 13.2. 

A partial AWT das 
hierarchy. 




A graphical user interface-based application that you writeby using theAWT can be as com pi ex 
as you like, with dozens of nested containers and components inside each other. AWT was 
designed so that each component can play its part in theoverall AWT system without needing 
to duplicate or keep track of the behavior of other parts in the system. 

The Basic User Interface Components 

T he simplest form of AWT component isthebasic U I component. You can createand add these 
to your applet without needing to know anything about creating containers or panels— your 
applet, even before you start painting and drawing and handling events, is already an AWT 
container. Because an applet is a container, you can put other AWT components— such asU I 
components or other containers- into it. 
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I n thissection, you’ll learn about thebasic U I components: labels, buttons, checkboxes, choice 
menus, and text fields. I n each case, the procedurefor creating thecomponent isthesame- you 
first createthecomponent, and then add itto thepanel that holdsit, at which point it isdisplayed 
on thescreen. To add a component to a panel (such as your applet, for example), usetheaddO 
method: 

public void init() { 

Button b = new Button ( "OK" ) ; 
add(b) ; 

> 

N otethatwherethecomponentappearsin the panel dependsonthelayout that panel isdefined 
to have. The default layout for panels such asappletsiSFiowLayout, with acentered alignment, 
which meansthat components are added from left to right in rows, and then row by row asthey 
fit, with each row centered. This explains why some of theexamples in thissection look a little 
funny. You’ll learn more about panels and layouts in the next section. 

N otealso that each of thesecomponentshasan action associated with it— that is, somethingthat 
component does when it’s activated. Actions generally trigger events or other activities in your 
applet (often called callbacks in other window toolkits). I n thissection, you’ll focuson creating 
the components themselves; you’ll learn about adding actions to them later in today’s lesson. 

On to the components! 

Labels 

T he simplest form of U I component is the label. 

NEW** Labelsare, effectively, text strings that you can use to label other U I components. 

TERM 

Theadvantagesthatalabel hasover an ordinary text string isthat itfollowsthelayout of thegiven 
panel, and you don’t have to worry about repainting it every time the panel is redrawn. Labels 
also can be easily aligned within a panel, enabling you to attach labels to other U I components 
without knowing exact pixel positions. 

T o create a label, use one of the following constructors: 

□ Label o creates an empty label, with its text aligned left. 

□ Labei(string) creates a label with thegiven text string, also aligned left. 

□ Label (string, int) creates a label with thegiven text string and thegiven alignment. 
The available alignments are stored in class variables in Label, making them easier to 
remember: Label. right, Label. left, and Label. center. 

T he label’s font is determined by the overall font for the component (as set by the setFont() 
method). 
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H ere's some simple code to create a few labels. Figure 13.3 shows how this looks on screen: 

add(new Label( "aligned left ")); 

add(new Label( "aligned center", Label. CENTER) ) ; 

add (new Label (" aligned right", Label. RIGHT) ) ; 



Figure 13.3. 

Labels 



aligned left 
aligned center 
aligned right 



Once you havea label object, you can use methods defined intheLabeidassto get and set the 
values of the text as shown in Table 13.1. 

Table 13.1. Label methods. 



Method 


Action 


getText() 


Returns a string containing this label’s text 


setText(String) 


Changes the text of this label 


getAlignment() 


Returns an integer representing the alignment of this label: 

0 is Label. LEFT, 1 is Label. CENTER, 2 iSLabel. RIGHT 


setAlignment(int) 


C hanges the alignment of this label to the given integer or class 
variable 



B uttons 

The second user interface component to explore is the button. 

NEW*- ButtonsaresimpleUI components that trigger some action in your interface when they 
TERM are pressed. For example, a calculator applet might have buttons for each number and 
operator, or a dialog box might have buttons for "OK” and "Cancel.” 

T o create a button, use one of the following constructors: 

□ Button o creates an empty button with no label. 

□ Button(string) creates a button with the given string object as a label. 
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Once you have a button object, you can get the value of the button's label by using the 
getLabeio method and set the label using the setLabei(string) methods. 

Figure 13.4 shows some simple buttons, created using the following code: 

add(new Button( "Rewind" )) ; 
add(new Button ( "Play" )) ; 
add(new Button("Fast Forward")); 
add(new Button( "Stop" ) ) ; 



Figure 13.4. 

Buttons 




Checkboxes 

C heckboxes can be selected or deselected to provide options. 

NEW«~ C heckboxesareuser interfacecomponentsthat have two states: on and off (or checked and 
TERM unchecked, selected and unselected, trueand false, and soon). U nlikebuttons, checkboxes 
usually don’t trigger direct actions in all I but, instead, are used to indicate optional featuresof 
some other action. 



C heckboxes can be used in two ways: 



□ N onexdusive, meaning that given a series of checkboxes, any of them can be selected. 

□ Exclusive, meaning that within one series, only one checkbox can be selected at a time. 



Thelatterkind of checkboxes are cal led radio buttonsor checkbox groups, and aredescribed in 
the next section. 

N onexdusivecheckboxescan becreated byusingthecheckbox class. You can create a checkbox 
by using one of the following constructors: 

□ checkbox o createsan empty checkbox, unselected. 

□ checkbox(string) creates a checkbox with the given string as a label. 

□ checkbox (string, nuii, boolean) creates a checkbox that is either selected or 
unselected based on whether the boolean argument is true or t aise, respectivdy. (T he 
nuii is used as a placeholder for a group argument. 0 nly radio buttons have groups, as 
you’ll learn in the next section). 




T able 13.2 lists the checkbox methods; Figure 13.5 shows a few simple checkboxes (only 
underwear is selected), generated using thefollowing code: 
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add(new Checkbox) "Shoes" )) ; 

add(new Checkbox) "Socks" )) ; 

add (new Checkbox) "Pants" )) ; 

add(new Checkbox) "Underwear" , null, true)); 

add (new Checkbox) "Shirt" )) ; 



Figure 13.5. 

C heckboxes 



A Red 
v'Blue 
* Yellow 
^Green 
v"Orange 
v"Purple 



Table 13.2. Checkbox methods. 



Method 


Action 


getLabel) ) 


Returns a string containing this checkbox’s label 


setLabel(String) 


C hanges the text of the checkbox’s label 


getstate) ) 


Returns true or false, based on whether the checkbox is selected 
or not 


setState(boolean) 


Changes the checkbox’s state to selected (true) or unselected 

(false) 



Radio Buttons 

Radio buttons are a variation on the checkbox. 

NEW*- Radio buttons have the same appearance as checkboxes, but only one in a series can be 
TERM selected at a time. 

T o create a series of radio buttons, first create an instance of checkboxGroup: 

CheckboxGroup cbg = new CheckboxGroup)); 
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Then create and add the individual checkboxes, using the group as the second argument, and 
whether or not that checkbox is selected (only one in the series can be selected): 

add(new Checkbox( "Yes" , cbg, true); 
add(new Checkbox) "no" , cbg, false); 

H ere’s a simple example (the results of which are shown in Figure 13.6): 



CheckboxGroup cbg = new CheckboxGroupO ; 



add(new Checkbox) 
add(new Checkbox) 
add(new Checkbox) 
add(new Checkbox) 
add(new Checkbox) 
add(new Checkbox) 



“Red", cbg, true)); 
"Blue", cbg, false)); 
"Yellow", cbg, false) 
"Green", cbg, false)) 
"Orange", cbg, false) 
"Purple", cbg, false) 



); 

); 



Figure 13.6. 

Radio buttons 



v-Red 
v bIue 
v Yellow 
v"Creen 
^Orange 
v"Purple 



All the check box methods defined in the previous section can be used with the checkboxes in 
the group. In addition, you can usethegetcheckboxGroup)) and setcheckboxGroup)) methods 
to access and change the group of any given checkbox. 

Finally, thegetcurrento and setcurrent (Checkbox) methods, defined in the checkbox group, 
can be used to get or set the currently selected checkbox. 




Choice Menus 

T he choice menu is a more complex U I component than labels, buttons, or checkboxes. 

NEW*~ Choicemenusarepopup (or pulldown) menusthatenableyou to select an item from that 
TERM menu. The menu then displays that choice on the screen. 

T o create a choice menu, create an instance of the choice class, and then use the additemo 
method to add individual itemsto it in theorder in which they should appear: 
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Choice c = new Choice(); 

c.addltem( "Apples" ) ; 
c.addltem( "Oranges" ) ; 
c.addItem("Strawberries“) ; 
c.addltem( "Blueberries" ) ; 
c.addltem( "Bananas" ) ; 

Finally, add the entire choice menu to the panel in the usual way: 

add(c) ; 

Figure 13.7 shows a simple choice menu generated from code in the previous example: 



Figure 13.7. 

Choice menus 



Apples 

Oranges 


d 


Strawberries 




Blueberries 




Bananas 






Tip: Choice menus enable only one selection per menu. If you want to select 
multiple items, use a scrolling list instead. 



Once your choice menu iscreated,regardlessof whether it'sadded to a panel, you can continue 
to add items to that menu by using the additemo method. T able 13.3 shows some other 
methods that may be useful in working with choice menus. 



Table 13.3. Choice menu methods. 

Method Action 

getitem(int) Returns the string item at the given position (items inside a choice 
begin at 0 , same as arrays) 

countitemso Returns the number of items in themenu 

getseiectedindexo Returns the index position of theitem that’s selected 
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M ethod Action 

getseiecteditemo Returns the currently selected item asa string 
select (int) Selects the item at the given position 

select (string) Selects the item with that string 



Text Fields 

U nlike the U I components up to this point, which enable you to select only among several 
options to perform an action, text fields allow you to enter any values. 

NEW** T fields enable your reader to enter text. 

TERM 

T o create a text field, use one of the following constructors: 

□ TextFieid ( ) creates an empty TextFieid 0 characters wide. 

‘if TextFieid (int) creates an empty text field with the given width in characters. 

JGJ TextFieid (string) createsatext field 0 characters wide, initialized with the given 
string. 

O TextFieid (string, int) createsatext field with the given width in characters and 
containing the given string. If the string is longer than the width, you can select and 
drag portions of the text within the field and the box will scroll left or right. 

For example, thefollowinglinecreatesatext field 30 characterswidewiththestring "Enter Your 
Name” as its initial contents. 

TextFieid tf = new TextField( "Enter Your Name", 30); 
add(tf ) ; 




Tip: T ext fields include only the editable field itself. You usually need to include a 
label with a text field to indicate what belongs in that text field. 



N ote: T ext fields are different from text areas; text fields are limited in size and are 
best used for one-line items, whereas text areas have scrollbars and are better for 
larger text windows. Both can be edited and enable selections with the mouse. 
You’ll learn about text areas lata today. 
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You can also create a text field that obscures the characters typed into it- for example, for 
password fields. T o dothis, first createthetextfieldsitself, and then usethesetEchocharactero 
method to set the character that is echoed on the screen. H ere is an example: 

TextField tf = new TextField(30) ; 
tf .setEchoCharacter( 

Figure 13.8 shows three text boxesfand labels) that were created by using the following code: 

add (new Label ("Enter your Name")); 

add (new TextField ("your name here", 45)); 

add(new Label( "Enter your phone number")); 

add (new TextField(12) ) ; 

add (new Label ("Enter your password")); 

TextField t = new TextField(20) ; 
t .setEchoCharacter( ' * 1 ) ; 
add(t) ; 

Figure 13.8. 

Text fields 




T ext fields inherit from the class Textcomponent and have a whole suite of methods, both 
inherited from that class and defined in its own class, that may be useful to you in your Java 
programs. T able 13.4 shows a selection of those methods. 



Table 13.4. Text field methods. 
Method Action 



getText() 
setText(String) 
getColumns() 
select(int, int) 

selectAll() 



Returns the text this text field contains (as a string) 

Puts the given text string into the field 

Returns the width of this text field 

Selects the text between the two integer positions (positions 

start from a) 

Selects all the text in the field 
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Method 




Action 

isEditabieo Returnstrue or false based on whether the text iseditableor 

not 

setEditabie( boolean) True (the default) enablestext to be edited; false freezes the text 
getEchochar ( ) Returns the character used for masking input 

echocharisseto Returns true or false whether the field has a masking character 

or not 



Panels and Layout 

You know at this point that an AWT panel can contain Ul components or other panels. The 
question now is how those components are actually arranged and displayed on the screen. 

In other windowing systems, Ul components are often arranged using hard-coded pixel 
measurements- put text field tf at 10,30, for example- the same way you used the graphics 
operationsto paint squares and ovalson thescreen. I n theAWT , thewindow may bedisplayed 
on many different windowing systems on many different screensand with many different kinds 
of fonts with different font metrics. Therefore, you need a more flexible method of arranging 
components on the screen so that a layout that looks nice on one platform isn’t a jumbled 
unusable mess on another. 



For just this purpose, Java has layout managers, insets, and hints that each component can 
provide for helping layout thescreen. 



N otethatthenicething about AWT componentsanduserinterfaceitemsisthatyou don't have 
to paint them— theAWT system manages all that for you. If you have graphical components 
or images, or you want to create animations inside panels, you still havetodothatby hand, but 
for most of the basic components, all you have to do is put them on thescreen and Java will 
handle the rest. 




Layout Managers 

Theactual appearanceof theAWT componentson thescreen isdetermined by two things: the 
order in which they are added to the panel that holdsthem, and the layout manager that panel 
is currently using to lay out the screen. The layout manager determines how portions of the 
screen will be sectioned and how components within that panel will be placed. 

N otethat each panel on thescreen can haveitsown layout manager. By nesting panelswithin 
panels, and using the appropriate layout manager for each one, you can often arrange your U I 
to group and arrange components in a way that isboth functionally useful and also looks good 
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on a variety of platforms and windowing systems. You’ll learn about nesting panels in a later 
section. 

The AWT provides four basic layout managers: FiowLayout, GridLayout, BorderLayout, and 
cardLayout. T o create a layout manager for a given panel, usethesetLayout ( > method for that 
panel: 

public void init() { 

this . setLayout (new FiowLayout ( ) ) ; 

} 

Setting the default layout manager, like defining the user interface components, is best done 
during the applet or class’s initialization, which is why it’s included here. 

Once the layout manager is set, you can start adding components to the panel. The order in 
which components are added is often significant, depending on which layout manager is 
currently active. Read on for information about the specific layout managers and how they 
present components within the panel to which they apply. 

The following sections describe the four basicJavaAWT layout managers. 

The FiowLayout Class 

T he FiowLayout dassisthemost basic of layouts. U sing theflow layout, components are added 
to the panel one at a time, row by row. If a component doesn't fit onto a row, it’s wrapped onto 
the next row. Theflow layout also has an alignment, which determines the alignment of each 
row. By default, each row is aligned centered. Figure 13.9 shows a flow layout at its best— a 
simple row of buttons, centered on a line. 




Figure 13.9. 

Flow layout. 




To creates basic flow layout with a centered alignment, 
panel’s initialization (because this isthe default pane layout, you 
if that is your intent): 



setLayout(new FlowLayout ( ) ) ; 

T o create a flow layout with an alignment other than centered, add the FlowLayout. right or 
FlowLayout. left class variable as an argument: 



set Layout (new FlowLayout ( FlowLayout . LEFT) ) ; 

You can also set horizontal and vertical gap values by using flow layouts. The gap isthenumber 
of pixels between components in a panel; by default, the horizontal and vertical gap values are 
three pixels, which can be very close indeed. H orizontal gap spreadsout componentsto the left 
and to theright, vertical gap to the top and bottom of each component. Add integer arguments 
to theflow layout constructortoincreasethegap(alayout gap oflOpointsinboththehorizontal 
and vertical directions is shown in Figure 13.10): 

setLayout(new FlowLayout (FlowLayout. LEFT) ,10,10) ; 



Figure 13.10. 

Flow layout witi 
10 points 




Grid Layouts 

G rid layouts use a layout that offers more control over the placement of componprtfcifiside a 
panel. U sing a grid layout, you portion off the area of the panel into rowsandMumns. Each 
component you then add to the panel is placed in a"ceH" of thegrid, startin#ram thetop row 
and progressing through each row from left to right (here'swheretheord^pfcallstotheadd() 
method are very relevant to how the screen islaid out). By using griilldyduts and nested grids, 
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you can often approximate the use of hard-coded pixel values to place your U I components 
precisely where you wantthem. Figurel3.ll showsagrid layout with three columns and three 
rows. 



Figure 13.11. 

Grid layout. 



T ocreateagrid layout, indicatethenumber of rowsandcolumnsyou want thegrid to havewhen 
you create a new instance of theGridLayout class: 

setLayout (new GridLayout(3,3) ) ; 

G rid layoutscan also havea horizontal and vertical gap between components; to creategaps, add 
those pixel values: 

setLayout (new GridLayout(3,3,10,15) ) ; 

Figure 13.12 shows a grid layout with a 10-pixel horizontal gap and a 15-pixel vertical gap. 

G rid bag layouts, asimplemented by theGridBagLayout class, arevariationson grid layouts. G rid 
bag layoutsal so enableyou to lay outyour user interfaceelementsinarectangular grid, but with 
grid bag layouts you havemuch morecontrol over the presentation of each element in thegrid. 
Grid bag layoutsusea helper class, GridBagconstramts, to indicate how each cell in thegrid is 
to be formatted. 



Note: TheGridBagLayout and GridBagconstraints classes were added to the Java 
Developer's Kit just before this book went to press. Foramuch better description 
of grid bag layouts, seetheAPI documentation for those classes that comes with 
theJDK. 
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Figure 13.12. 

Grid layouts with horizontal 
and vertical gap. 
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Border Layouts 

Border layouts behave differently from flow and grid layouts. When you add a component to 
a panel that uses a border layout, you indicate its placement as a geographic direction: north, 
south, east, west, and center (see Figure 13.13). The components around all the edges are laid 
out with as much size asthey need; thecomponent in the center, if any, gets any space I eft ova. 



Figure 13.13. 

Border layout. 





T o use a borda layout, you create it as you do the otha layouts: 

setLayout(new BorderLayout() ) ; 
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Then you add the individual components by using a special addo method: the first argument 
to addo is a string indicating the position of the component within the layout: 

add ( “North" , new TextField( "Title" ,50) ) ; 
add( “South" , new TextField("Status" ,50) ) ; 

You can also usethisform of add( ) for theother layout managers; thestring argument will just 
be ignored if it’s not needed. 

Border layouts can also have horizontal and vertical gaps. N ote that the north and south 
components extend all the way to the edge of the panel, so the gap will result in less space for 
theeast, right, and center components. To add gapsto a border layout, indudethose pixel values 
as before: 

setLayout (new BorderLayout(10,10) ) ; 



Card Layouts 

C ard layoutsaredifferent from theother layouts. Unlikewith theotherthreelayouts, when you 
add components to a card layout, they are not all displayed on the screen at once. Card layouts 
areused to produce slideshowsof components, oneatatime. If you'veever used theH yperC ard 
program on theM acintosh, you’ve worked with the same basic idea. 

Generally when you createacard layout, thecomponentsyou add to it will be other container 
components- usually panels. You can then usedifferent layoutsforthoseindividual "cards” so 
that each screen has its own look. 

W hen you add each "card” to the panel, you can give it a name. T hen you can use methods 
defined on thecardLayout dassto move back and forth between different cards in the layout. 

For example, here's how to create a card layout containing three cards: 

setLayout (new CardLayoutO) ; 

Panel one = new Panel () 
add( “first" , one); 

Panel two = new Panel () 
add ( “second" , two); 

Panel three = new Panel() 
add( “third", three); 
show(this, "second"); 

Insets 

W hereas horizontal gap and vertical gap are used to determine the amount of space between 
componentsin apanel, insetsareused to determinetheamount of space around the panel itself. 
T he insets class provides valuesfor the top, bottom, left, and right insets, which are then used 
when the panel itself is drawn. Figure 13.14 shows an inset in aGridLayout. 
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Figure 13.14. 

Insets. 
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To include an inset, overridethemsetso method in your cl ass (your Applet dassor other class 
that serves as a panel): 

public Insets insets() { 

return new Insets(10, 10, 10, 10) ; 

> 

Theargumentsto the Insets constructor provide pixel insetsfor thetop, bottom, left, and right 
edgesof the panel. Thisparticular example provides an inset of 10 pixelson all four sides of the 
panel. 



Handling Ul Actions and Events 

If you stopped reading today’s lesson right now, you could go out and create an applet that had 
lotsof little U I components, nicely laid out on the screen with the proper layout manager, gap, 
and insets. If you did stop right here, however, your applet would be really dull, because none 
of your U I components would actually do anything when they were pressed or typed into or 
selected. 






Foryour U I componentsto do something when they areactivated, you need to hook up thell I 's 
action with an operation. 

T estingfor an action by aU I component isaform of event management— thethingsyou learned 
yesterday about events will come in handy here. In particular, U I components produce the 
special kind of event called an action. T o intercept an action by any U I component, you define 
an action o method in your applet or class: 
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public boolean action(Event evt, Object arg) { 

> 

The action o method should look familiar to the basic mouse and keyboard event methods. 
Likethosemethods, it gets passed theevent object that representsthisevent. It also gets an extra 
object, which can be of any type of object. W hat’s that second argument for? 

Thesecond argument to theaction method dependson thell I component that’sgenerating the 
event. The basic definition isthat it'sany arbitrary argument — when a component generates an 
event, it can pass along any extra information that might later be needed. Because that extra 
information may be useful for you, it’s passed on through theactiono method. 

All thebasicll I components (except for labels, which haveno action) havedifferentactionsand 
arguments: 

Z Buttons create actions when they are selected, and a button's argument is the label of 
the button. 

□ Checkboxes, both exclusive and nonexclusive, generate actions when a box is checked. 
T he argument is always true. 

□ C hoice menus generate an action when a menu item is selected, and the argument is 
that item. 

Z Text fields create actions when theuser pressesReturn inside that text field. Note that 
if the user tabs to a different text field or uses the mouse to change the input focus, an 
action is not generated. Only a Return triggers the action. 

N otethatwith actions, unlikewith ordinary events, you can havemany different kindsof objects 
generating the event, as opposed to a single event such as a mouseDown. T o deal with those 
different U I components and the actions they generate, you have to test forthetypeof object 
that called the event in thefirst place inside the body of your action < ) method. T hat object is 
stored in the event’s target instance variable, and you can usethemstanceof operator to find 
out what kind of U I component sent it: 

public boolean action(Event evt, Object arg) { 
if (evt. target instanceof TextField) 
handleText(evt. target) ; 
else if (evt. target instanceof Choice) 
handleChoice(arg) ; 



> 

Although you can handle U I actions in the body of the actiono method, it’s much more 
common simply to define a handler method and call that method from action {) instead. H ere, 
there are two handler methods: one to handle the action on the text field (handieTexto) and 
oneto handle the action on the choice menu (handiechoiceo). Depending on theaction you 
want to handle, you may also want to passon theargument from theaction, thell I component 
that sent it, or any other information that theevent might contain. 
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H ere's a simple applet that has five buttons labeled with colors The action o method tests for 
a button action and then passes off the word to a method called changecoioro, which changes 
the background color of the applet based on which button was pressed (see F igure 13.15 to see 
the applet in action): 

import java.awt.*; 

public class ButtonActionsTest extends java. applet. Applet { 

public void init() { 

setBackground(Color. white) ; 

add (new Button ( "Red" )) ; 
add (new Button ( “Blue" )) ; 
add(new Button("Green“)) ; 
add (new Button ( "White" )) ; 
add(new Button( "Black" )) ; 

} 

public boolean action(Event evt, Object arg) { 
if (evt. target instanceof Button) 
changeColor( (String)arg) ; 
return true; 



void changeColor(String bname) { 

if (bname . equals( "Red" ) ) setBackground(Color.red) ; 
else if ( bname. equals) "Blue" ) ) setBackground(Color.blue) ; 
else if (bname. equals) "Green" ) ) setBackground(Color. green) ; 
else if (bname. equals) "White" ) ) setBackground (Color. white) ; 
else setBackground(Color. black) ; 



Figure 13.15. 

T he B uttonA cti on applet. 
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Nesting Panels and Components 

Adding Ul components to individual applets is fun, but applets begin to turn into lots of fun 
when you begin working with nested panels. By nesting different panelsinsideyour applet, and 
panelsinsidethose panels, you can create d i f f eren 1 1 ayo u ts f o r d i f f eren t p arts of t h e o veral I applet 
area, isolate background and foreground colors and fonts to individual parts of an applet, and 
manage the design of your U I components much more cleanly and simply. T he more complex 
the layout of your applet, the more likely you’re going to want to use nested panels. 

Nested Panels 

Panels, as you’ve already learned, are components that can be actually displayed on screen; 
panei’ssuperdasscontainerprovidesthegeneric behaviorfor holding other componentsinside 
it. T he Applet class, which your applets all inherit from, is a subclass of panel. To nest other 
panelsinsidean applet, you merely create a new panel and add it to theapplet, just asyou would 
add any other U I component: 

setLayout (new GridLayout(1 ,2,10,10)); 

Panel panell = new Panel(); 

Panel panel2 = new Panel(); 
add(panel1 ) ; 
add(panel2) ; 

You can then set up an independent layout for those subpanels and add AWT componentsto 
them (including still more subpanels) by calling the addo method in the appropriate panel: 

panell . setLayout ( new FlowLayout ( ) ) ; 
panell .add(new Button("Up")) ; 
panell .add (new Button ( "Down" ) ) ; 

Although you can do all thisin a singleclass, it’scommon in appletsthat makeheavy use of the 
panels to factor out the layout and behavior of the subpanels into separate classes, and to 
communicate between the panels by using method calls. You’ll look at an extensive example of 
this later on in today’s lesson. 

Events and Nested Panels 

When you create appletswith nested panels, those panelsform a hierarchy from theoutermost 
panel (theapplet, usually), to theinnermost U I component. This hierarchy is important to how 
each component in an applet interacts with the other components in the applet or with the 
browser that containsthat applet; in particular, the component hierarchy determines the order 
in which components are painted to the screen. 

M ore importantly, the hierarchy also affects event handling, particularly for user input events 
such as mouse and keyboard events. 
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Events are received bytheinnermost component inthecomponent hierarchy and passed upthe 
chain to theroot. Suppose, for example, that you have an applet with asubpanel that can handle 
mouse events(usingthemouseDown( ) and mouseupo methods) and that panel containsabutton. 
Clicking on the button means that the button receives the event before the panel does; if the 
button isn't interested in thatmouseDowno, the event gets passed to the panel, which can then 
process it or pass it further up the hierarchy. 

Remember the discussion about the basic event methods yesterday? You learned that the basic 
event methodsall return boolean values. Those boolean values become important when you’re 
talking about handling events or passing them on. 

An event handling method, whether it is the set of basic event methods or the more generic 
handieEvento, can do oneof three things, given any random event: 

□ N ot be interested in the event (this is usually true only for handieEvent ( ), which 
receives all the events generated by the system). If this is the case, the event is passed 
on up the hierarchy until a component processes it (or it is ignored altogether). I n this 
case, the event handling method should return false. 

□ Intercept the event, process it, and return true. In this case, the event stops with that 
event method. Recall that this is the case with the basic mouseDowno and keyDowno 
methods that you learned about yesterday. 

□ I ntercept the method, process it, and pass it on to the next event handler. T his is a 
more unusual case, but you may create a user interface by using nested components 
that will want to do this. I n this case, the event method should return false to pass 
the event on to the next handler in the chain. 

MoreUI Components 

Once you master the basic U I components and how to add them to panels and manage their 
events, you can add morell I components. I n thissection, you’ll learn about text areas, scrolling 
lists, scrollbars, and canvases. 

N ote that the U I components in this section do not produce actions, so you can't use the 
actiono method to handle their behavior. Instead, you have to use a generic handieEvento 
method to test for specific events that these Ul components generate. You’ll learn more about 
this in the next section. 

Text Areas 

T ext areas are like text fields, except they have more functionality for handling large amounts 
of text. Because text fields are limited in size and don’t scroll, they are better for one-line 
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responses and text entry; text areas can be any given width and height and have scrollbars in 

default, so you can deal with larger amounts of text more easily. 

T o create a text area, use one of the following constructors: 

Z TextAreat ) creates an empty text area 0 rows long and 0 characters wide. G iven that a 
text area with no dimensions can’t bedisplayed, you should makesureyou change the 
dimensions of this new text area before adding it to a panel (or just use the next 
constructor instead). 

□ TextArea(int, int) creates an empty text area with the given rows and columns 
(characters). 

5ZfextArea(string) creates a text area displaying the given string, 0 rows by 0 columns. 

□ TextArea(string, int, int ) creates a text area by displaying the given string and with 
the given dimensions. 

Figure 13.16 shows a simple text area generated from the following code: 

String str = "Once upon a midnight dreary, while I pondered, weak and weary, \n" + 
"Over many a quaint and curious volume of forgotten lore,\n" + 

“While I nodded, nearly napping, suddenly there came a tapping, \n“ + 

“As of some one gently rapping, rapping at my chamber door.\n" + 

" \ " 'Tis some visitor, \“ I muttered, Vtapping at my chamber door-\n"; 

add(new TextArea(str, 10,60) ) ; 



Figure 13.16. 

A text area. 



Once upon a midnight dreary, while I pondered, weak and weary, 
over many a quaint and curious volume of forgotten lore, 

While l nodded, nearly napping, suddenly there came atapping, 

As of some one gently rapping, rapping at my chamber door. 

'"Tis some visitor," I muttered, 'tapping at my chamber door- 
only this, and nothing more." 

Ah, distinctly I remember it was in the bleak December, 

And each separate dying ember wrought its ghost upon the floor. 
Eagerly I wished the morrow;- vainly I had sought to borrow 






Both text areas and text fields inherit from theiextcomponent class, so a lot of the behavior for 
text fields(parti cularly gettingand settingtext and selections) isusableon text areas aswell (refer 
to Table 13.4). Text areas also have a number of their own methods that you may find useful. 
T able 13.5 shows a sampling of those methods. 
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Table 13.5. Text area methods. 

M ethod Action 



getColumns() 

getRows() 



insertText (String, int) 



replaceText(String, int, int) 



Returns the width of the text area, in characters or 
columns 

Returns the number of rows in the text area (not the 
number of rows of text that the text area contains) 
Inserts the string at the given position in the text (text 
positions start at 0) 

Replace the text between the given integer positions 
with the new string 



Scrolling Lists 

Remember the choice menu, which enables you to choose one of several different options? A 
scrolling list isfunctionally similar to achoice menu in that it lets you pick several optionsfrom 
a list. Scrolling lists differ in two significant ways: 

□ Scrolling lists are not popup menus. T hey’re lists of items in which you can choose 
one or more items from a list. If the number of items is larger than the list box, a 
scrollbar is automatically provided so that you can see the other items. 

,L A scrolling list can be defined to accept only one item at a time (exclusive), or multiple 
items (nonexclusive). 

T 0 create a scrolling list, create an instance of the List class and then add individual items to 
that list. The List class has two constructors: 

□ iiist ( ) creates an empty scrolling list that enables only one selection at a time. 

m List (int, boolean) creates a scrolling list with the given number of visible lines on 
the screen (you’re unlimited as to the number of actual items you can add to the list). 

T he boolean argument indicates whether this list enables multiple selections (true) or 
not (false). 

After creating a List object, add items to it using the additemo method and then add the list 
itself to the panel that contains it. H ere’san example, the result of which is shown in Figure 
13 . 17 : 

List 1st = new List(5, true); 

1st. addltem( "Hamlet") ; 

1st .addltem( "Claudius" ) ; 
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lst.addltem( "Gertrude" ) ; 
1st . addltem( "Polonius" ) ; 
1st . addltem( "Horatio" ) ; 
1st . addltem( "Laertes" ) ; 
1st . addltem( "Ophelia" ) ; 

add (1st) ; 



Figure 13.17. 

A scrolling list. 




T able 13.6 shows someof the methods available to scrolling lists. SeetheAPI documentation 
for a complete set. 

Table 13.6. Scrolling list methods. 



Method 


Action 


getltem(int) 


Returns the string item at the given position 


countltems() 


Returns the number of items in the menu 


getSelectedlndex() 


Returns the index position of the item that's selected (used for 
lists that enable only single selections) 


getSelectedlndexes( ) 


Returns an array of index positions (used for lists that enable 
multiple selections) 


getSelectedltem() 


Returns the currently selected item as a string 


getSelectedltems() 


Returns an array of strings containing all the selected items 


select(int) 


Selects the item at the given position 


select(String) 


Selects the item with that string 



Scrollbars and Sliders 

T ext areas and scrolling lists come with their own scrollbars, which are built into those U I 
components and enableyou to manage both the body of the area or the list and its scroll bar as 
asingleunit. You can also createindividual scrollbars, or sliders, to manipulatearangeof values. 
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Scroll bars are used to select a value between a maximum and a minimum value. To change the 
current value of that scrollbar, you can use three different parts of the scrollbar (see Figure 
13 . 18 ): 

□ Arrows on either end, which increment or decrement the values by some small unit (i 
by default). 

□ A rangein the middle, which increments or decrements the value by a larger amount 
(10 by default). 

□ A box in the middle, often called an elevator or thumb, whose position shows where in 
the range of values the current value is located. M oving this box with the mouse 
causes an absolute change in the value, based on the position of the box within the 
scrollbar. 



Choosing any of these visual elements causes a change in the scrollbar's value; you don’t have 
to update anything or handleany events. All you haveto do i s gi ve th e scrol I bar a maximum and 
minimum, and Java will handle the rest. 

T 0 create a scrollbar, you can use one of three constructors: 

p scroiibaro creates a scrollbar with 0, 0 as its initial maximum and initial minimum 
values, in a vertical orientation. 

□ scroiibar(int) creates a scrollbar with 0, 0 as its initial maximum and initial mini- 
mum values. The argument represents an orientation, for which you can use the class 

Variables Scrollbar. HORIZONTAL and Scrollbar. VERTICAL. 

( I scroiibar(int, int, int, int, int) creates a scrollbar with the following arguments 
(each one is an integer, and must be presented in this order): 

The first argument is the orientation of the scrollbar: scrollbar, horizontal and 



Figure 13.18. 

Scrollbar parts 




Box (elevator, thumb) 



Scrollbar. VERTICAL. 
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The second argument is the initial value of the scrollbar, which should be a value 
between the scrollbar’s maximum and minimum values. 

The third argument is the the overall width (or height, depending on the orientation) 
of the scrollbar's box. In user interface design, a larger box implies that a larger 
amount of the total range is currently showing (applies best to things such as windows 
and text areas). 

The fourth and fifth arguments are the minimum and maximum values for the 
scrollbar. 

H ere'sasimpleexampleofascrollbarthatincrementsasinglevalue(seeFigurel3.19).Thelabel 
to the left of the scrollbar is updated each time the scrollbar's value changes: 

import java.awt.*; 

public class SliderTest extends java. applet. Applet { 

Label 1; 



public void init ( ) { 

1 = new Label) "0"); 
add(l) ; 

add(new Scrollbar(Scrollbar. HORIZONTAL, 1, 0, 1, 100)); 

} 

public boolean handleEvent(Event evt) { 
if (evt. target instanceof Scrollbar) { 

int v = ( (Scrollbar)evt. target) .getValue() ; 
l.setText(String.valueOf ( v ) ) ; 

} 

return true; 

} 

> 



Figure 13.19. 

A scrollbar. 
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T he scroiibar class provides several methods for managing the values within scrollbars (see 
Table 13.7). 

Table 13.7. Scrollbar methods. 

Method Action 

getMaximumo Returns the maximum value 

getMinimumo Returnsthe minimum value 
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Method 



Action 



getOrientation() 



getvalue( ) 
setvalue(int) 



R etu rns the ori entati on of th i s scrol I bar: 
0 for vertical, i for horizontal 
Returns the scrollbar’s current value 
Sets the current value of the scrollbar 



Canvases 

Although you can draw on most AWT components, such as panels, canvasesdo littleexcept let 
you draw on them. T hey can’t contain other components, but they can accept events, and you 
can createanimationsand display imageson them. Canvases, in otherwords, should beused for 
much of the stuff you learned about earlier this week. 

NEW«~ A canvas is a component that you can draw on. 

TERM 

T o create a canvas, usethecanvas cl ass and add it to a panel asyou would any other component: 

Canvas can = new Canvas(); 
add(can) ; 



More Ul Events 



Yesterday, you learned about some basic event types that are generated from user input to the 
mouse or the keyboard. These event types are stored in theEvent object astheevent ID , and can 
be tested for in the body of a handieEvent ( > method by using class variables defined in Event. 
For many basic events, such asmouseDowno and keyDowno, you can define methods for those 
eventstohandletheevent directly. You learned asimilar mechanism today for U I actionswhere 
creating an action o method handled a specific action generated by a U I component. 

The most general way of managing events, however, continuesto bethehandieEvento method. 
Forevents relating to scrollbars and scrolling lists, the only way to intercept these events is to 
Override handieEvent ( ) . 




T o intercept a specific event, test for that event’s I D . T he available I D s are defined as class 
variables in theEvent class, so you can test them by name. You learned about some of the basic 
events yesterday; T able 13.8 shows additonal events that may be useful to you for the 
components you’ve learned about today (or that you might find useful in general). 
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Table 13.8. Additional events. 



Event ID 


What It Represents 


ACTION_EVENT 


Generated when a U 1 component action occurs 


KEY_ACTION 


Generated when text field action occurs 


LIST_DESELECT 


Generated when an item in a scrolling list is deselected 


LIST_SELECT 


Generated when an item in a scrolling list is selected 


SCROLL_ABSOLUTE 


Generated when a scrollbar's box has been moved 


SCROLL_LINE_DOWN 


Generated when a scrollbar's bottom endpoint (or left endpoint) is 
selected 


SCROLL_LINE_UP 


Generated when a scrollbar's top endpoint (or right endpoint) is 
selected 


SCROLL_PAGE_DOWN 


Generated when the scrollbar’s field below (or to the left of) the 
box is selected 


SCROLL_PAGE_UP 


Generated when the scrollbar's field above (or to the right of) the 
box is selected 



A Complete Example: 

RGB to HSB Converter 

Let’s take a break here from theory and smaller examples to create a larger, more complex 
example that puts together much of what you’ve learned so far. T hefollowing applet example 
demonstrates layouts, nesting panels, creating user interface components, and catching and 
handling actions, as well as using multiple classes to put together a single applet. In short, it’s 
probably the most complex applet you’ll create so far. 

Figure 13.20 showsthe applet you’ll be creating in this example. T he ColorTest applet enables 
you to pick colors based on RGB (red, green, and blue) and HSB (hue, saturation, and 
brightness) values. 



Figure 13.20. 

TheColorT est applet. 
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T heC olorT est applet has three main parts: a colored box on the left side and two groupsof text 
fields on the right. The first group indicates RGB values, the right, H SB. By changing any of 
the values in any of thetext boxes, the colored boxisupdated to thenew color, as are the values 
in the other group of text boxes. 

This applet uses two classes: 

□ coionest, which inherits from Applet. This is the controlling class for the applet 
itself. 

□ coiorcontrois, which inherits from panel. You’ll create this class to represent a group 
of three text fields and to handle actions from those text fields. Two instances of this 
class, onefortheRGB values and onefor theH SB ones, will be created and added to 
the applet. 

Let'swork through thisstep by step, because it'svery complicated and can get confusing. All the 
code for this applet will be shown at the end of this section. 

Create the Applet Layout 

T hebest way to start creating an applet that usesA W T components isto worry about thelayout 
first and then worry aboutthefunctionality. W hen dealing with thelayout, you also should start 
with the outermost panel first and work inward. 

M aking asketch of your U I design can helpyoufigureouthowtoorganizethepanelsinsideyour 
applet or window to best take advantage of layout and space. F igu re 13.21 showstheC olorT est 
applet with a grid drawn over it so that you can get an idea of how the panels and embedded 
panels work. 

Figure 13.21. 

T heColorT est applet panels 
and components 




Create the Panel Layout 

Let’s start with the outermost panel— the applet itself. T his panel has three parts: the color box 
on the left, the RG B text fields in the middle, and the H SB fields on the right. 

Because thisisthe applet, yourcoionest class will be theapplet class and inherit from Applet. 
You’ll also import theAWT classes here (note that because you use so many of them in this 
program, it’s easiest to just import the entire package): 
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import java.awt.*; 

public class ColorTest extends java. applet. Applet { 



Let'sstartwiththeinito method, where all thebasic initialization and I ayo u t takes p I ace. There 
are four major steps: 

1. Set the layout for the big parts of the panel. Although a flow layout would work, a 
grid layout with one row and three columns is a much better idea. 

2. Create the three components of this applet: a canvas for the color box and two 
subpanels for the text fields. 

3. Add those components to the applet. 

4. Finally, initialize the default color and update all thepanelsto reflect that default 
color. 

Before you do any of that, let’sset up instance variables to hold the threemajor components of 
thisapplet. You need to keep hold of theseobjectssoyou can updatethingswhen avaluechanges. 

T he color box is easy— it’s just a canvas. C all it swatch. 

Canvas swatch; 

N ow onto the subpanels. There are two of them, and although they have different labels and 
values, they'reessenti ally thesamepanel. You could just createcodefor each onehere, but you’d 
end up duplicating a lot of the same code. T his is a perfect opportunity, therefore, to create 
another cl ass to represent the subpanels with thetextfieldson them. Call themcoiorcontrois 
(you’ll get around to creating the class later) and define two variables, RGBcontrols and 
HSBcontrois, to hold them: 

ColorControls RGBcontrols, HSBcontrois; 

Backtotheimto method. Step oneisthelayout. Let'suseagrid layout and agap of ten points 
to separate each of the components: 

setLayout (new GridLayout (1 ,3,10,10)); 

Step two iscreatingthecomponents, thecanvas first. You have an instance variableto hold that 
one: 

swatch = new Canvas(); 

You need to createtwo instancesof your as-of-yet nonexistentcoiorcontrois panelshereaswell, 
but you don't know exactly what you need to create them yet, so let’s put in some basic 
constructors and fill in the details later: 

RGBcontrols = new 
HSBcontrois = new 
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ColorControls () 
ColorControls () ; 



Step three is adding them to the panel. 

add(swatch) ; 
add(RGBcontrols) ; 
add(HSBcontrols) ; 

While you’re working on layout, add an inset just for fun— ten points along all the edges: 

public Insets insets() { 

return new Insets(10, 10, 10,10) ; 

> 

Got it so far? Now you have a skeleton mito method and an msetso method in your 
coiorTest class. Let’smoveon now to creati n g thesu bpan el layout— tocreatingthatcoiorcontrois 
class. 



D efine the Subpanels 

T he coiorcontrois class will have behavior for laying out and handling the subpanels that 
represent the RGB and H SB values for the color, coiorcontrois doesn't need to be a subclass 
of Applet because it isn't actually an applet, it's just a panel. D efine it to inherit from panel: 

class ColorControls extends Panel { 



Note: You can put the coiorcontrois classin the same file as the coiorTest class. 
You haven't been doing this so far because the applets and applications you’ve been 
creating had only one class. If you remember way back to D ay 1, however, you 
learned that you can have multiple class definitions in a single file as long as only 
one of those definitions is declared public. I n this case, the coiorTest class is 
public (it’s an applet, so it has to be), but the coiorcontrois class doesn’t need to 
be, so everything works out fine. 



You need a coupleof instance variables in this class. Thefirst thing you need isa hook back up 
to the applet class that contains this panel. W hy? The applet class is the class that oversees how 
thesubcomponentswork,soit’sgoingto be the cl ass that updates everything. Eventually, you’re 
going to have to call a method in that cl ass to indicatethat something in this panel haschanged. 
Without an actual reference to that outer class, there's no way to do this. So, instance variable 
number one is a reference to the class coiorTest: 

CoiorTest outerparent; 

I f you figure that the applet class is the one that's going to be updating everythi ng, that class is 
going to need a way to get hold of the pieces inside this class. In particular, it’s going to be 
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interested in the individual text fields, so you’re going to need instance variables to hold those. 
This creates three of them: 

TextField f 1 , f2, f3; 

N ow for the constructor for this class. Again, this isn’t an applet, so you don’t use mit o; all 
you need is a constructor method. 

What do you need inside that constructor? You need to set the layout for the subpanel, create 
the text fields, and add them to the panel. The goal here is to make the coiorcontrois class 
generic enough so that you can use it for both the RGB fields and the H SB fields. 

T hetwo different panelsdiffer in two respects: the labelsforthetext fields, and theinitial values 
for the text fields. That’s six values to get before you can create the object. You can pass those 
six valuesin through the constructors in coionest. You also need onemore. Because you need 
that hook back to the applet class, you should also pass in a reference to that object as part of 
the constructor. 

You now have seven arguments to the basic constructor for thecoiorcontrois class. H ere'sthe 
signature for that constructor: 

ColorControls (ColorTest target, 

String 11, String 12, String 13, 
int vl , int v2, int v3) { 

> 

Given those arguments, you can assign the right values to your instance variables: 

outerparent = target; 

fl = new TextField (String. valueOf(v1 ) , 10) ; 
f 2 = new TextField (String. value0f(v2) , 10) ; 
f3 = new TextField(String. valueOf (v3) , 10) ; 

N otethat becausethefirst argument to theTextFieid constructor isastring, and thevaluesthat 
you passed in wereintegers, you have to usethevaiueot o class method (defined in string) to 
convert the integer to a string before creating each text field. 

N ext, you createthe layout for this panel. You also useagrid layout for these subpanels, as you 
did for theapplet panel, but thistimethegrid will have three rows (onefor each ofthetext field 
and label pairs) and two columns (one for the labels and one for the fields). 

Given the 3-by-2 grid, you can now add the text fields and labels to that panel. N otethat by 
separating the labels and thetext fields into separate cel Is in the grid, you can align the labels, 
creating a nice aligned layout. 

add (new Label(11, Label. RIGHT) ) ; 
add(fl); 

add (new Label(12, Label. RIGHT) ) ; 
add(f2) ; 
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add (new Label(13, Label. RIGHT) ) ; 
add(f3) ; 

Finally (because I like insets), you’ll inset the contents of the subpanel a bit- only on the top 
and bottom edges- by including an insets o method: 

public Insets insets() { 

return new Insets(10, 10,0,0) ; 

} 

You’re almost there. You have 98 percent of the layout in place and ready to go, but you’re 
missing two things: creating thecoiorcontroisobjectsincoionest, and initializing everything 
so that all the components have the right values. 

F or both, you need to go back to thecoionest class and theimt < ) method you defined there. 
Let'sstart with theinitialization part, becausethat'seasy.T hedefaultcolor isblack. Set up alocal 
variable to hold that color object: 

Color theColor = new Color(0,0,0) ; 

T o set the initial color of the color box, all you need to do is set its background: 

swatch. setBackground (theColor) ; 

N ow, let’s finally tackle initializing those subpanels. The constructor for coiorcontrois has 
seven arguments: thecoionest object, threelabels(strings), and threeinitial valuesforthetext 
fields (integers). Let’sdotheRGB controls first, because you can easily extract the initial red, 
green, and blue values out of the color object: 

RGBcontrols = new ColorControls(this, “Red", "Green", "Blue", 
theColor. getRed() , theColor. getGreen() , 
theColor. getBlue()); 

Things get complicated on the H SB side of the panel. The color class provides you with a 
method to get the H SB values out of a color object, but there are two problems: 

□ TheRGBtoHSBo method is a single class method that insists on returning an array of 
the three values. 

P TheH SB values are measured in floating-point values. I prefer to think of H SB as 
integers, wherein the hue is a degree value around a color wheel (0 through 360), and 
saturation and brightness are percentages from 0 to 100. H aving H SB as integer values 
also enables you to have a generic subpanel, as was the intent. 

I nitializing the H SB subpanel is going to be a little difficult. 

First, let’s extract those FI SB values. Given that the method takes three RGB arguments- an 
array of three floats- and returns an array of three floats, you have to go through this process 
to get those values: 

float[ ] HSB = Color . RGBtoHSB (theColor . getRed ( ) , 

theColor. getGreen() , theColor. getBlue() , (new float[3])); 
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N ow you have an array of floats, whereHSBio] is the hue, hsbmi is the saturation, and hsb[2] 
isthe brightness. You can now (finally!) initializethe H SB side of the applet, making sure that 
when you passthoseH SB valuesinto the subpanel, you multiply them by the right values (360 
for the hues, 100 for the saturation and the brightness) and convert them to integers: 

HSBcontrols = new ColorControls(this, 

"Hue", "Saturation", "Brightness", 

(int) ( HSB [ 0 ] * 360), (int) (HSB[1 ] * 100), 

(int) (HSB[2] * 100)); 

Ready to giveup?Fear not- you’vedonethehard part. From here, it’s(mostly) easy. Onceyou 
have your layout working, you can compile your Java program and see how it looks. N one of 
your U I components actually does anything, but perfecting the layout is half the battle. 

H andle the Actions 

After creating the layout, you set up actions with the U I components so that when the user 
interacts with the applet, the applet can respond. 

T heaction of thisappletoccurswhentheuserchangesavaluein any of thetext fields. By causing 
an action in atext field, thecolor changes, thecolor box updatesto thenew color, and the values 
of the fields i n the opposite subpanel change to reflect the new color. 

Thecoionest class is responsiblefor actually doing the updating, because it keeps track of all 
the subpanels. You should be tracking and intercepting eventsin the subpanel in which they 
occur, however. Becausetheaction of theapplet isan actual text action, you can use an action < ) 
method to intercept it: 

public boolean action (Event evt, Object arg) { 
if (evt. target instanceof TextField) { 
this.outerparent.update(this) ; 
return true; 

> 

else return false; 

} 

In the action o method, you test to make sure the action was indeed generated by a text field 
(because there are only text fields available, that'sthe only action you’ll get, but it'sa good idea 
to test for it anyhow). If so, call theupdateo method, defined in coionest, to updatetheapplet 
to reflect all the new values. Because the outer applet is responsiblefor doing all the updating, 
this is precisely why you need that hook back to theapplet— so you can call the right method 
at the right time. 

U pdate the Result 

T heonly part left now isto updateall thevaluesand thecolor swatch if oneof thevalueschanges. 
For this, you define theupdateo method in thecoionest class. This update o method takes 
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a single argument— thecoiorcontrois instance that contains the changed value (you get that 
argument from theactiono method in the subpanel). 



Note: Won’t this update o method interfere with the system’s update o method? 
N ope. Remember, methods can have the same names, but different signatures and 
definitions. Because this update o has a single argument of typecoiorcontrois, it 
doesn't interfere with the other version of updateo. 



T he update ( > method is responsible for updating all the panels in the applet. T o know which 
panel to update, you need to know which panel changed. You can find out by testing to see 
whether the argument you got passed is the same as the subpanels you have stored in the 
RGBcontrois and HSBcontrois instance variables: 
void update (ColorControls in) { 

if (in == RGBcontrois) { // the change was in RGB 



else { // change was in HSB 

> 



Thistestistheheartoftheupdateo method. Let’sstart with that first case- a number hasbeen 
changed in theRG B text fields. So now, based on thosenew RGB values, you have to generate 
a new color object and updatethevalueson theH SB panel. To reduce sometyping, you create 
a few local variables to hold some basic values. I n particular, the values of the text fields are 
strings, and you get into them by accessing the text field instance variables forthecoiorcontrois 
panel (ti, t2, t3) and then using thegetTexto method to extract theactual values. Extract those 
values and store them in string variables so that you don’t have to keep typing: 

String vl = in.fl .getText() ; 

String v2 = in.f2.getText() ; 

String v3 = in.f3.getText() ; 

G iven those string values for RG B, you now create a color object by converting those strings to 
integers: 




Color c; 

c = new Color(Integer.parseInt(v1 ), Integer. parselnt(v2) , 
Integer . parselnt (v3) ) ; 



N ote: T his part of the example isn't very robust; it assumes that the user has indeed 
entered real numbers into the text fields. A better version of this would test to make 
sure that no parsing errors had occurred (I was trying to keep this example small). 
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When you have a color object, you can update the color swatch: 

swatch. setBackground(c) ; 

The next step is to update theHSB panel to the new HSB values. Doing thisin theimto 
method isnofun at all, and it'sevenlessfun here. T odothis,youcallRGBtoHSBto getthefloating- 
point values, convert them to integers with the right values, convert them to strings, and then 
put them back into the text fields for the H SB subpanel. Got all that? H ere's the code: 

float [] HSB = Color. RGBtoHSB(c.getRed() ,c.getGreen() , 
c.getBlue(), (new float[3] ) ) ; 

HSB [ 0 ] *= 360; 

HSB [ 1 ] *= 100; 

HSB [ 2 ] *= 100; 

HSBcontrols.fi . setText (String . valueOf ( (int)HSB[0] ) ) ; 

HSBcontrols . f 2 . setText (String . valueOf ( (int ) HSB [ 1 ] ) ) ; 

HSBcontrols . f 3 . setText (String . valueOf ( (int ) HSB [ 2] ) ) ; 

The second part of the update o method iscalled when avalueon theH SB side of the panel is 
changed. This is the "else” in the if-else that determines what to update, given achange. 

Believe it or not, it’s easier to update RGB values given H SB than it is to do it the other way 
around. First, convert thestringvaluesfrom theH SB text fieldsto integers by using these lines: 

int fl = Integer. parselnt(v1 ) ; 

int f 2 = Integer. parselnt(v2) ; 

int f3 = Integer. parselnt(v3) ; 

T here’sa class method in the color class that createsa new color object when given three H SB 
values. The catch is that those values are floats, and they’re not the values you currently have. 
Tocall getHSBCoioro (that’sthenameof themethod), convert theintegersto floats and divide 
by the right amounts: 

c = Color. getHSBColor( (float)fl / 360, (float)f2 / 100, (float)f3/l00) ; 

N ow that you have a color object, the rest is easy. Set the color swatch: 

swatch. setBackground(c) ; 

Then update the RGB text fields with the new RGB values from the color object: 

RGBcontrols.fi . setText (St ring. valueOf (c.getRed() ) ) ; 

RGBcontrols.f2. setText (String .valueOf (c.getGreen( ) ) ) ; 

RGBcontrols . f 3 . setText (St ring . valueOf (c . getBlue ( ) ) ) ; 

The Complete Source Code 

Listing 13.1 shows the complete source code; often it’s easier to figure out what’s going on in 
this applet when it’s all in one place and you can follow themethod calls and how values are 
passed back and forth. Start with the imt < > method in applet, and go from there. 
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Listing 13.1. The ColorT est applet. 

import java.awt.*; 

public class ColorTest extends java. applet. Applet { 

ColorControls RGBcontrols, HSBcontrols; 

Canvas swatch; 

public void init() { 

Color theColor = new Color(0,0,0) ; 
float[ ] HSB = Color . RGBtoHSB (theColor . getRed ( ) , 
theColor. getGreen() , theColor. getBlue() , 
(new float[3] )) ; 

setLayout (new GridLayout(1 ,3,10,10)); 

// The color swatch 

swatch = new Canvas(); 

swatch. setBackgroundf theColor) ; 

// the control panels 

RGBcontrols = new ColorControls(this, 

“Red", "Green", "Blue", 
t heColor. getRed () , theColor. getGreen ( ) , 
theColor. getBlue( ) ) ; 

HSBcontrols = new ColorControls(this, 

"Hue", "Saturation", "Brightness", 

(int) ( HSB [ 0 ] * 360), (int) ( HSB [ 1 ] * 100), 
(int) (HSB[2] * 100)); 

add(swatch) ; 
add(RGBcontrols) ; 
add(HSBcontrols) ; 




public Insets insets() { 

return new Insets(10,10,10,10) ; 



void update(ColorControls in) { 

Color c; 

String vl = in.fl .getText() ; 

String v2 = in.f2.getText() ; 

String v3 = in.f3.getText() ; 

if (in == RGBcontrols) { // change to RGB 

c = new Color(Integer.parseInt(v1 ) , 
Integer. parselnt(v2) , 

Integer. parselnt (v3) ) ; 
swatch. setBackground(c) ; 




continues 
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Listing 13.1. continued 

float[ ] HSB = Color. RGBtoHSB(c.getRed() ,c.getGreen() , 
c.getBlue(), (new float[3] ) ) ; 

HSB[0] *= 360; 

HSB[ 1 ] *= 100; 

HSB[2] *= 100; 

HSBcontrols.fi . setText (String . valueOf ( (int ) HSB[0] ) ) ; 
HSBcontrols .f 2. setText (String. valueOf ( (int) HSB [1 ] ) ) ; 
HSBcontrols .f 3. setText (String. valueOf ( (int) HSB[2] ) ) ; 

} 

else { // change to HSB 

int fl = Integer. parselnt(vl) ; 

int f 2 = Integer. parselnt(v2) ; 

int f3 = Integer. parselnt(v3) ; 

c = Color. getHSBColor( (float)fl / 360, 

(float)f2 / 100, (float)f3/100) ; 
swatch. setBackground(c) ; 

RGBcontrols.fi .setText (String. valueOf (c.getRedO) ) ; 
RGBcontrols . f 2 . setText (St ring . valueOf ( 
c.getGreen() ) ) ; 

RGBcontrols .f 3. setText (String. valueOf (c.getBlue( ) ) ) ; 



class ColorControls extends Panel { 

TextField fl, f2, f 3 ; 

ColorTest outerparent; 

ColorControls (ColorTest target, 

String 11, String 12, String 13, 
int vl , int v2, int v3) { 

this. outerparent = target; 

set Layout (new GridLayout (3,4, 10, 10) ) ; 

fl = new TextField (String. valueOf (vl ) ,10) ; 
f 2 = new TextField(String. valueOf (v2) ,10) ; 
f3 = new TextField(String. valueOf (v3) ,10) ; 

add(new Label(ll , Label. RIGHT) ) ; 
add(fl); 

add (new Label (12, Label. RIGHT) ) ; 
add(f2) ; 

add(new Label(13, Label. RIGHT) ) ; 
add(f3) ; 



public Insets insets() { 

return new Insets(10, 10,0,0) ; 

} 

public boolean action(Event evt, Object arg) { 
if (evt. target instanceof TextField) { 
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this.outerparent.update(this) ; 
retrue true; 



} 

else return false; 



Summary 

TheJavaAWT, or Abstract Windowing Toolkit, is a package of Java classes and interfaces for 
creat i n g f u 1 1 -f I ed ged accessto awindow-based graphical user interfacesystem, with mechanisms 
for graphics display, event management, text and graphics primitives, user interface compo- 
nents, and cross- platform layout. The AWT is used by the H otjava browser itself for all its 
functionality. Applets are also an integral part of the AWT toolkit. 

T oday has been a big day; the lesson has brought together everything you’ve learned up to this 
point about simpleapplet management and added a lot moreabout creating applets, panels, and 
user interface components and managing the interactions between all of them. With the 
information you got today and the few bits that you’ll learn tomorrow, you can create cross- 
platform Java applications that do just about anything you want. 



Q&A 

Q You've mentioned a lot about the component and container classes, but it looks 
like the only container objects that ever get created are Panels. W hat do the 
component and container classes give me? 

A Those classes factor out the behavior for components (generic AWT components) and 
containers (components that can contain other components). Although you don’t 
necessarily create direct instances of these classes, you can create subclasses of them if 
you want to add behavior to theAWT that the default dassesdo not provide. As with 
most of the Java classes, any time you need a superclass's behavior, don’t hesitate to 
extend that class by using your own subclass. 

Q Can I put a Ul component at a specific x and y position on the screen? 

A By using the existing layout managers supplied with theAWT toolkit, no. This is 
actually a good thing because you don’t know what kind of display environment your 
applet will be run under, what kind of fonts are installed, or what kind of fonts are 
being currently used. By using the layout managers provided with theAWT, you can 
be sure that every portion of your window will be viewable and readable and usable. 
You can't guarantee that with hard-coded layouts. 
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Q I was exploring the AWT package, and I saw this subpackage called peer. There's 
also references to the peer classes sprinkled throughout the API documentation. 
What do peers do? 

A Peers are responsible for the platform-specific parts of the AWT. For example, when 
you create a Java AWT window, you have an instance of the window class that provides 
generic W indow behavior, and then you have an instance of windowPeer that creates 
the very specific window for that platform— a motif window under X windows, a 
M acintosh-style window under the M acintosh, or a Windows 95 window under 
Windows 95. The peers also handle communication between the window system and 
thejava window itself. By separating the generic component behavior (theAWT 
classes) from the actual system implementation and appearance (the peer classes), you 
can focuson providing behavior in your Java application and let thejava implementa- 
tion deal with the platform-specific details. 

Q There’s a whole lot of functionality in theAWT that you haven't talked about 
here. Why? 

A G iven that even a basic introduction took this long, I figured that if I put in even 
more detail than I already have that this book would turn into Teach Yourself Java in 
21 DaysPlusa Few Extra for theAWT Stuff. 

As it is, I’ve left windows, menus, and dialog until tomorrow, so you’ll have to wait 
for those. But you can find out about a lot of the other features of AWT merely by 
exploring the API documentation. Start with the Applet class and examine the sorts of 
methodsyou can call. Then look at panel, from which applet inherits- you have all 
that class’s functionality as well. The superclass of panel is container, which provides 
still more interesting detail, component comes next. Explore the API and see what you 
can do with it. You might find something interesting. 
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Windows, 
Networking, and 
Other Tidbits 



by Laura Lemay 



Windows, Networking, and Other Tidbits 



H ereyou areon thelast day of the second week, and you'rejust aboutfinished with applets and 
theAWT . W ith the information you’ll learn today, you can createawidevariety of applets and 
applicationsusingj ava. N extweek'slessonsprovidemoreof theadvanced stuff that you 'I I need 
if you start doing really serious work in Java. 

Today, to finish up this week, there are three very different topics: 

i'-'l Windows, menus, and dialog boxes— the last of theAWT classes that enable you to 
pop up real windows from applets, and to create stand-alone Java applications that 
have their own windows 

□ N etworking— how to load new H TM L files from an applet-capable browser, how to 
retrieve files from Web sites, and some basics on how to work with generic sockets in 
Java 

□ Extra tidbits — the smaller stuff that didn't fit in anywhere else, but that might be 
useful to you as you write your Java applets and applications 

Windows, Menus, and Dialog Boxes 

T oday, you’ll finish up thelast bitsof theAWT that didn’t fit into yesterday'slesson. In addition 
to all the graphics, events, U I , and layout mechanisms that theAWT provides, it also provides 
windows, menus, and dialog boxes, enabling to you create fully featured applications either as 
part of your applet or independently for stand-alonej ava applications. 

Frames 

TheAWT window class enables you to create windows that are independent of the browser 
window containing the applet— that is, separate popup windows with their own titles, resize 
handles, and menubars. 

The window class provides basic behavior for windows. M ost commonly, instead of using the 
window class, you’ll use window’s subclasses, Frame and Dialog. The Frame class enables you to 
createa fully functioning window with a menubar. Dialog isa more limited window for dialog 
boxes. You’ll learn more about dialog boxes later on in this section. 

T o create a frame, use one of the following constructors: 

□ new Frame o creates a basic frame without a title. 

□ new Frame (string) creates a basic frame with the given title. 

Frames are containers, just I ike pan els are, so you can add other componentsto them just asyou 
would regular panels, using theaddo method. Thedefault layout forwindowsiSBorderLayout: 

win = new Frame) "My Cool Window"); 
win.setLayout(new BorderLayout(10,20) ) ; 




win. add ("North", new Button ( "start" )) ; 
win .add( "Center" , new Button( "Move" ) ) ; 

To set a size for the new window, use the resize ( ) method. T o set a location for where the 
window appears, usethemoveo method. N ote that the location o method can tell you where 
theappletwindowisonthescreensothatyou can pop up theextrawindow in arelative position 
to that window (all thesemethodsaredefined forall containers, so you can usethem for applets, 
windows, and the components inside them, subject to the current layout): 

win.resize(100,200) ; 

Dimension d = location(); 

win. move(d. width + 50, d. height + 50); 

When you initially create a window, it’s invisible. You need to usetheshowo method to make 
the window appear on the screen (you can use hide o to hide it again): 



Listing 14.1 shows an example of a simple applet with a popup window (both the applet and 
the window are shown in Figure 14.1). The applet has two buttons: oneto show the window, 
and oneto hide the window. The window itself, created from a subclass called MyFrame has a 
singlelabel: "This is a window. "You’ll usethisbasic window and applet all through thissection, 
so the more you understand what’s going on herethe easier it will be later. 



Type 



Listing 14.1. A popup window. 



public class GUI extends java. applet. Applet { 
Frame window; 



public void init() { 

add(new Button("Open Window")); 
add(new Button( "Close Window")); 



window = new MyFrame (“A Popup Window"); 
window. resize(150, 150) ; 
window. show() ; 



public boolean action(Event evt, Object arg) { 
if (evt. target instanceof Button) { 

String label = (String)arg; 

if (label. equals("Open Window")) { 
if (Iwindow.isShowingO) 
window. show() ; 

} 

else if (label == "Close Window") { 
if (window.isShowingO) 
window. hide() ; 

} 

return true; 



continues 





Windows, Networking, and Other Tidbits 



Listing 14.1. continued 

else return false; 

> 

} 

class MyFrame extends Frame { 
Label 1; 



MyFrame(String title) { 
super(title) ; 

setLayout(new GridLayout (1 , 1 ) ) ; 

1 = new Label ( "This is a Window", Label. CENTER) ; 
add(l) ; 



Menus 

Each new window you create can have its own menubar along the top of the screen. Each 
menubar can haveanumber of menus, and each menu, in turn, can havemenu items. TheAWT 
provides classes for all these things called, respectively, MenuBar, 
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Add individual menus (File, Edit, and so on) to themenubar by creating them and then adding 
them to themenubar: 

Menu m = new Menu ( "File" ) ; 
mb.add(m) ; 

Somesystemsenableyou to indicateaspecial help menu, which may bedrawn on theright side 
of the menubar. You can indicate that a specific menu is the help menu by using the 
setHeipMenuo method. T he given menu should already be added to the menu itself: 

Menu hm = new Menu ( "Help" ) ; 
mb.add(hm) ; 
mb.setHelpMenu(hm) ; 

I f, for any reason, you want to prevent a user from selecting a menu, you can use thedisabie ( ) 
command on that menu (and the enable o command to make it available again): 

m.disable() ; 



Menu Items 

There are four kinds of items you can add to individual menus: 

□i Instances of the class Menuitem, for regular menu items 
□ I nstances of the class checkBoxMenuitem, for toggled menu items 
jEt Other menus, with their own menu items 
O Separators, for lines that separate groups of items on menus 

Regular menu itemsare added by using theMenuitem class. Add them to a menu using theadd( ) 
method: 

Menu m = new Menu( "Tools" ) ; 
m.add(new Menultem( " Info" ) ) ; 
m.add(new Menultem( "Colors" )) ; 
m.add(new Menultem( "Sizes" )) ; 

Submenuscan beadded simply by creatinganewinstanceofMenu and addingittothefirst menu. 
You can then add items to that menu: 

Menu sb = new Menu( "Sizes" ) ; 
m.add(sb) ; 

sb.add(new Menultem( "Small" )) ; 
sb.add(new Menultem( "Medium" ) ) ; 
sb.add(new Menultem( "Large" )) ; 

T hecheckBoxMenuitem class creates a menu item with a checkbox on it, enabling themenu state 
to be toggled on and off (selecting it once makes the checkbox appear selected; selecting it again 
unselectsthecheckbox). C reateand add acheckboxmenu item thesamewayyou createand add 
regular menu items: 
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CheckboxMenuItem coords = 

new CheckboxMenuItem( "Show Coordinates"); 
m.add(coords) ; 

Finally, to add a separate) rtoamenu(alineusedtoseparategroupsofitemsinamenu), create 
and add a menu item with the label n - " . 

Menultem msep = new Menultem( " - " ) ; 
m.add(msep) ; 

Any menu item can be disabled by using the disabieo method and enabled again using 
enabieo. Disabled menu items cannot be selected: 

Menultem mi = new Menultem( "Fill" ) ; 
m.addltem(mi) ; 
mi.disable() ; 



Menu Actions 

The act of selecting a menu item causes an action event to degenerated. You can handle that 
action the same way you handle other action methods— by overriding actiono. Both regular 
menu itemsand checkbox menu itemshaveactionsthatgeneratean extra argument representing 
the label for that menu. You can use that label to determine which action to take. N ote, also, 
that because checkBoxMenuitem isasubdassof Menultem, you don’t have to treat that menu item 
as a special case: 

public boolean action(Event evt, Object arg) { 
if (evt. target instanceof Menultem) { 

String label = (String)arg; 

if (label. equals( "Show Coordinates" ) ) toggleCoords() ; 
else if (label. equals("Fill")) fillcurrentArea( ) ; 
return true; 

} 

else return false; 

> 



An Example 

Let’s add a menu to the window you created in the previous section. Add it to the constructor 
method in theMyFrame class (Figure 14.2 shows the resulting menu): 

MyFrame(String title) { 
super(title) ; 

MenuBar mb = new MenuBar(); 

Menu m = new Menu ( "Colors" ) ; 

m.add(new Menultem( "Red" ) ) ; 

m.add(new Menultem( "Blue" ) ) ; 

m.add(new Menultem( "Green" )) ; 

m.add(new Menultem( " - " ) ) ; 

m.add(new CheckboxMenuItem( "Reverse Text")); 

mb.add(m) ; 
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mb.setHelpMenu(m) ; 
setMenuBar(mb) ; 



This menu has four items: one each for the colors red, blue, and green (which, when selected, 
change the background of the window), and one checkbox menu item for reversing the color 
of the text (to white). T o handle these menu items, you need an action o method: 

public boolean action (Event evt, Object arg) { 
if (evt. target instanceof Menultem) { 

String label = (String)arg; 

if (label. equals ( "Red" ) ) setBackground(Color.red) ; 
else if (label. equals) "Blue" ) ) setBackground(Color.blue) ; 
else if (label. equals) "Green" ) ) setBackground(Color. green) ; 
else if (label. equals) "Reverse Text")) { 
if (getForeground() == Color. black) 
setForeground(Color. white) ; 
else setForeground(Color. black) ; 

} 

return true; 

} 

else return false; 

> 



fm A Popup Windo 


Colors | 


I Red 




Blue 


■ 


Green 


j Reverse Text 
Set Text.** 



Dialog Boxes 

D ialog boxes arefunctionally similar to framesin that they pop up new windowson thescreen. 
H owever, dialog boxes are intended to be used for transient windows- for example, windows 
that let you know about warnings, windows that ask you for specific information, and so on. 
D ialogs don't usually have titlebars or many of the more general features that windows have 
(although you can create one with a titlebar), and they can be madenonresizableor modal. 
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NEW«~ A modal dialog prevents input to any of the other windows on thescreen until that dialog 
TERM is dismissed. 

TheAWT providestwo kindsof dialog boxes: theDiaiog class, which providesa generic dialog, 
and FiieDiaiog, which produces a platform-specific dialog to choose files to save or open. 

T o create a generic dialog, use one of these constructors: 

□ Dialog (Frame, boolean) creates an initially invisible dialog, attached to the current 
frame, which is either modal (true) or not (false). 

□ Diaiog(Frame, string, boolean) is the same as the previous constructor, with the 
addition of a titlebar and a title indicated by the string argument. 

Note that because you have to give a dialog a Frame argument, you can attach dialogs only to 
windows that already exist independently of the applet itself. 

The dialog window, like the frame window, is a panel on which you can layout and draw U I 
components and perform graphics operations, just as you would any other panel. Like other 
windows, thedialog isinitially invisible, butyou can show it with shown and hideitwithhideo. 

Let’sadd adialog to that same example with the popup window. You’ll add amenu item for 
changing thetext of the window, which bringsup the Enter T ext dialog box (see Figure 14.3). 

Figure 14.3. 

TheEnterText dialog. 




T oaddthisdialog, first add amenu item to that window (theconstructor method forthewiyFrame 
class) to change the text the popup window displays: 

m.add(new Menultem( "Set Text...")); 

Inthatsamemethod.you cancreatethedialog and lay out thepartsof it (it’sinvi si bleby default, 
so you can do whatever you want to it and it won't appear on screen until you show it): 



Warning: Applet Window 
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dl = new Dialog(this, "Enter Text", true); 
dl.setLayout(new GridLayout(2,1 ,30,30)) ; 



tf = new TextField(l.getText() ,20) ; 
dl.add(tf); 

dl. add (new Button( "OK" ) ) ; 
dl.resize(l50,75) ; 

T he action of choosing the menu item you just added brings up the dialog; choosing the 0 K 
button dismisses it. So you need to add behavior to thisclass'saction method so that the dialog 
works right. To the menu item tests, add alineforthenew menu item: 

if (evt. target instanceof Menultem) { 

if (label. equals( "Red" ) ) setBackground(Color. red) ; 
if (label. equals( "Blue" ) ) setBackground(Color.blue) ; 
if (label. equals( "Green" ) ) setBackground(Color. green) ; 
if (label. equals ("Set Text...")) dl.showj); 

> 

Then, because ok is a button, you have to add a special case for that button separate from the 
menu items. In this special case, set the text of the window to the text that was typed into the 
text field, and then hide the dialog again: 

if (evt. target instanceof Button) { 
if (label. equals( "OK" ) ) { 
l.setText (tf .getText ( ) ) ; 
dl.hide() ; 

} 

} 



File Dialogs 

FiieDiaiog providesa basic fileopen/savedialog box that enables you to access the file system. 
T heFiieDiaiog dassissystem-independent, but depending on theplatform, thestandard 0 pen 
File dialog is brought up. 



Note: For applets, you can bring up the file dialog, butdueto security restrictions 
you can’t do anything with it (or, if you can, access to any files on the local system 
is severely restricted). FiieDiaiog is much more useful in stand-alone applications. 



T o create a file dialog, use the following constructors: 

Ip FiieDiaiog (Frame, string) creates an Open File dialog, attached to the given frame, 
with the given title. T his form creates a dialog to load a file. 

IIP FiieDiaiog (Frame, string, int) also creates a file dialog, but that integer argument is 
used to determine whether the dialog is for loading a file or saving a file (the only 
difference is the labels on the buttons; the file dialog does not actually open or save 
anything). The possible options for the mode argument are FiieDiaiog. load and 

FiieDiaiog. SAVE. 
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After you create a FiieDiaiog instance, use showo to display it: 

FileDialog fd = new FileDialog(this, "FileDialog" ) ; 
fd.show() ; 

When the reader choosesafileinthefiledialog anddismissesit,you can then get to thefilethey 
chose by using the getDirectoryo and getFiieo methods; both return strings indicating the 
values the reader chose. You can then open that file by using the stream and file handling 
methods (which you’ll learn about next week) and then read from or write to that file. 



Window Events 

Yesterday, you learned about writing your own event handler methods, and you noted that the 
Event dassdefines many standard eventsfor which you can test. W indow events are part of that 
list, so if you usewindows, these eventsmaybeof interest to you. Table 14.1 showsthose events. 



T able 14.1: Window Events from the Event Class. 

window_destroy Generated when a window is destroyed (for example, when the 
browser or applet viewer has quit) 

window_expose Generated when the window is brought forward from behind other 
windows 

window_iconify Generated when the window isiconified 
window_deiconify Generated when the window is restored from an icon 
window_moved Generated when the window is moved 



Using AWT Windows 
in Stand-Alone Applications 

Because framesaregeneral-purposemechanismsforcreatingAWT windowswith panels, you 
can use them in your stand-alone Java applications and easily take advantage of all the applet 
capabilitiesyou learned about this week. T o do this, writeyour application asif it were an applet 
(inheriting from theAppiet class and using threads, graphics, and U I componentsasnecessary), 
and then add a main o method. H ere's one for a class called MyAWTClass: 

public static void main (String args[]) { 

Frame f = new Frame ("My Window 1 ’); 

MyAWTClass mac = new MyAWTClass ( ) ; 
mac.init() ; 
mac. start () ; 

f .add( "Center" , mac); 
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f .resize(300, 300); 
f .show() ; 



This main o method does five things: 

3 ft creates a new frame to hold the applet. 

:i Itcreatesan instance of the class that defines that method. 

B It duplicatesthe applet environment callstoinito andstartQ. 

ft adds the applet to the frame and resizes the frame to be 300 pixels square. 

□ ft shows the frame on the screen. 

By using this mechanism, you can create a Java program that can function equally well as an 
applet or an application- just include mito for applets and maino for applications. 

If you do create an application that usesthismechanism, be careful ofyourmito methodsthat 
get parameters from an H T M L file. W hen you run an applet as an application, you don’t have 
the HTML parameters passed into the mito method. Pass them in as command-line 
arguments, instead, and handlethem in your main< ) method. T hen set aflag so that the mito 
method doesn’t try to read parameters that don’t exist. 



Networking in J ava 

N etworking isthecapability of making connectionsfrom your applet or application to asystem 
over the network. N etworking in Java involves classes in thejava.net package, which provide 
cross- platform abstractions for simple networking operations, including connecting and 
retrieving files by using common Web protocols and creating basic Unix-like sockets. Used in 
conjunction with input and output streams (which you’ll learn much more about next week), 
reading and writing files over the network becomes as easy as reading or writing to files on the 
local disk. 



There are restrictions, of course. Java applets cannot read orwritefromthediskon themachine 
that’s running them. D epending on the browser, J ava applets may not be able to connect to 
systemsotherthan theoneupon which they were ori gi nal ly stored . Even given these restrictions, 
you can still accomplish a great deal and take advantage of the Web to read and process 
information over the net. 

This section describes three ways you can communicate with systems on the net: 

ID showDocumento, which enables an applet to tell the browser to load and link to 
another page on the W eb 

□ openstreamo, a method that opens a connection to a U RL and enables you to extract 
data from that connection 
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□ The socket classes, socket and serversocket, which enable you to open standard 
socket connections to hosts and read to and write from those connections 

C reating L inks I nside Applets 

Probably the easiest way to use networking inside an applet is to tell the browser running that 
applet to load a new page. You can use this, for example, to create animated image maps that, 
when clicked, load a new page. 

T o link to a new page, you create a new instance of the class URL. You saw some of this when 
you worked with images, but let’s go over it a little more thoroughly here. 

The url class represents a uniform resource locator. To create a new URL, you can use one of 
four different forms: 

□ url (st ring, string, int, string) creates a new U RL object, given a protocol (http, 
ftp, gopher, file), a host name (www.ine.com, ftp.netcom.com), a port number (so for 
http), and a filename or pathname. 

□ url (string, string, string) does the same thing as the previousform, minus the 
port number. 

□ url (url , string) creates a U RL, given a base path and a relative path. For the base, 
you can usegetDocumentBaseo for the URL of the current HTM L file, or 
getcodeBase for the U RL of thej ava class file. T he relative path will be tacked onto 
the last directory in those base URLs (just like with images and sounds). 

□ url (string) creates a URL object from a U RL string (which should include the 
protocol, hostname, and filename). 

Forthatlastone(creatingaURLfromastring),you have to catch a malformed URL exception, 
so surround the URL constructor with a try. . .catch: 

String url = "http://www.yahoo.com/"; 
try ( theURL = new URL(url); > 
catch ( MalformedURLException e) { 

System. out. println("Bad URL: " + theURL); 

} 

Getting a URL object is the hard part. Once you have one, all you have to do is pass it to the 
browser. Do this by using this single line of code, where theURL is the URL object to link to: 

getAppletContext() .showDocument (theURL) ; 

The browser that contains your U RL will then load and display the document at that URL. 

Listing 14.2 shows a simple applet that displays three buttons that represent important W eb 
locations (the buttonsare shown in Figure 14.4). Clicking on thebuttonscausesthedocument 
to be loaded to the locations to which those buttons refer. 
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Listing 14.2. Bookmark buttons. 

import java.awt.*; 

import java. net. URL; 

import j ava . net . Malt ormedURLException ; 

public class ButtonLink extends java. applet. Applet { 
Bookmark bmlist[] = new Bookmark[3]; 
public void init() { 

bmlist[0] = new Bookmark( "Laura 1 s Home Page", 
"http: //www. lne.com/lemay/") ; 
bmlist [1] = new Bookmark ( "Yahoo" , 

"http: //www. yahoo. com") ; 
bmlist[2]= new Bookmark( " Java Home Page", 
"http://java.sun.com"); 

setLayout (new GridLayout(bmlist .length, 1 , 10,10) ) ; 
for (int i = 0; i < bmlist. length; i++) { 
add(new Button(bmlist[i] .name) ) ; 



public boolean action(Event evt, Object arg) { 
if (evt. target instanceof Button) { 

LinkTo( (String)arg) ; 
return true; 

} 

else retrurn false; 



void LinkTo(String name) { 

URL theURL = null; 

for (int i = 0; i < bmlist. length; i++) { 
if (name. equals(bmlist[i] .name) ) 
theURL = bmlist[i] .url; 

} 

if (theURL ! = null) 

getAppletContext() . showDocument (theURL) ; 

} 



class Bookmark { 

String name; 

URL url; 

Bookmark (String name, String theURL) { 
this. name = name; 

try ( this. url = new URL(theURL) ; > 
catch ( MalformedURLException e) { 
System. out. println("Bad URL: " + 

} 




theURL); 
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Figure 14.4. 

Bookmark buttons 

Lauras Home Page 



Yahoo 



jaua Home Page 



m T wo classes make up this applet: the first implements the actual applet itself, the second 
IflyaS is a class representing a bookmark. Bookmarks have two parts: anameand aURL. 

This particular applet creates three bookmark instances and stores them in an array of 
bookmarks (this applet could be easily modified to make bookmarks as parameters from an 
HTML file). For each bookmark, a button iscreated whoselabel isthevalueof thebookmark’s 
name. 

When the buttons are pressed, theiinkToo method is called, which tells the browser to load 
the U RL referenced by that bookmark. 

Opening Web Connections 

Rather than asking the browser to just load thecontents of afile, sometimes you might want to 
get hold of that file’s contents so that your applet can use them. If thefileyou want to grab is 
stored on theWeb, and can be accessed using the more common U RL forms (http, ftp, and so 
on), your applet can use the URL class to get it. 

N otethat for security reasons, applets can connect back only to the same host from which they 
originally loaded. This means that if you have your applets stored on a system called 
www.myhost.com, the only machineyour applet can open a connection to will be that same host 
(and that same host name, so be careful with host aliases). If thefiletheapplet wantsto retrieve 
is on that same system, using U RL connections is the easiest way to get it. 
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openStreamO 

U RL defines a method called openstreamo, which opens a network connection using thegiven 
U RL and returns an instance of the class inputstream (part of the java.io package). If you 
convert that stream to aDatainputstream (with aButteredinputstream in themiddlefor better 
performance), you can then read characters and lines from that stream (you’ll learn all about 
streamson Day 19). For example, theselinesopenaconnection to thell RL stored in thevari able 
theuRL, and then read and echo each line of the file to the standard output: 

try { 

Inputstream in = theURL. openStream() ; 

DatalnputStream data = new DatalnputStream( 
new BufferedlnputStream(in) ; 

String line; 

while ((line = data.readLineO) != null) { 

System. out .println( "line" ) ; 

} 

> 

catch (lOException e) { 

System. out. println("IO Error: “ + e.getMessage()) ; 

> 



Note: You need to wrap all those lines in a try. . .catch statement to catch 
lOException exceptions. 



H ere’san example of an applet that uses the openstreamo method to open a connection to a 
Website, readsafilefrom that connection (Edgar Allen Poe’spoem "TheRaven"), and displays 
the result in atextarea. Listing 14.3 shows the code; Figure 14.5 shows the result after the file 
has been read. 



Listing 14.3. The GetRaven class. 

1: import java.awt.*; 

2: import java.io. DatalnputStream; 

3: import j ava. io . But f eredlnputStream; 

4: import java.io. lOException; 

5: import java. net. URL; 

6: import j ava. net . URLConnection ; 

7: import java. net. MalformedURLException; 

8: 

9: public class GetRaven extends java. applet. Applet 
10: implements Runnable { 





continues 
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Listing 14.3. continued 



12 

13 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

40 

42 

43 

44 

45 

46 

47 

48 

49 

50 

51 

52 

53 

54 

55 

56 

57 

58 

59 

60 
61 
62 

63 

64 

65 



URL theURL; 

Thread runner; 

TextArea ta = new TextArea( "Getting text. ,30,70) ; 
public void init() { 

String url = "http://www.lne.com/Web/Java/raven.txt"; 
try { this. theURL = new URL(url); } 
catch ( MalformedURLException e) { 

System. out. println("Bad URL: " + theURL); 

> 

add(ta) ; 



public Insets insets() { 

return new Insets(10, 10, 10, 10) ; 



public void start/) { 

if (runner == null) { 

runner = new Thread(this) ; 
runner. start ( ) ; 

> 



public void stop() { 

if (runner != null) { 
runner. stop() ; 
runner = null; 

> 

> 

public void run() { 

InputStream conn = null; 

DatalnputStream data = null; 

String line; 

StringBuffer buf = new StringBuffer( ) ; 
try { 

conn = this. theURL. openStream() ; 
data = new DataInputStream(new BufferedInputStream( 
conn)); 

while ((line = data.readLineO) != null) { 
buf .append(line + " \ n " ) ; 

} 

ta . setText (buf . tost ring ( ) ) ; 

} 

catch (lOException e) { 

System. out. println("IO Error:" + e.getMessage()) ; 
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Theinito method (lines 16 to 24) sets up the URL and the text area in which that file 
will bedisplayed. T heU RL could beeasily passed into theapplet viaan HTML parameter; 
here, it’s just hard-coded for simplicity. 

Because it might take some timeto load thefileover the network, you put that routine into its 
own thread and use the familiar starto, stopo, and runo methods to control that thread. 

Insideruno (lines 44 to 64), the work takes place. H ere, you initializea bunch of variables 
and then open the connection totheURL (using theopenstreamo method in line 51). 0 nee 
the connection is open, you set up an input stream in lines 52 to 56 and read from it, line by 
line, putting the result into an instance of stringButfer (a string buffer isa modifiablestring). 

0 nee all thedata has been read, Iine59 converts the stringButfer object into a real string and 
then puts that result in the text area. 

0 ne other thing to note about this example is that the part of the code that opened a network 
connection, read from thefile, and created a string issurrounded by atry and catch statement. 
If any errors occur whileyou’re trying to read or process the file, these statements enableyou to 
recover from them without the entire program crashing (in this case, the program exits with an 
error, because there’s little else to be done if theapplet can’t read thefile). try and catch give 
you the capability of handling and recovering from errors. You’ll learn more about exceptions 
on D ay 18. 
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The URLconnection Class 

URL'SopenStreamO method isactuallyasimplified USeoftheURLconnection daSS. URLconnection 
providesaway to retrievefilesby using URLs- on W ebor FTP sites, for examplauRLconnection 
also enables you to create output streams if the protocol allows it. 

To use a U RL connection, you first create a new instance of the class URLconnection, set its 
parameters (whether it enables writing, for example), and then use the connect o method to 
open theconnection. Keep in mind that, with aU RL connection, thedasshandlesthe protocol 
foryou based on the first part of the U RL, so you don’t have to makespecific requests to retrieve 
a file; all you have to do is read it. 



Sockets 

F or networking applications beyond what theuRL and URLconnection dassesoffer (for example, 
for other protocolsor for more general networking applications), J ava provides thesocket and 
serversocket classes as an abstraction of standard socket programming techniques. 
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Note: I don’t have the space to give you a full explanation of how socket program- 
ming works. If you haven’t worked with sockets before, see whether openst ream o 
will meet your needs. If you really need to do more, any book that discusses socket 
programming will give you the background you need to work with Java’s sockets. 



Thesocket dassprovidesadient-sidesocketinterfacesimilartostandardUnixsockets.T oopen 
aconnection, createanew instance of socket (where hostname isthe host to connect to, and 
portnum isthe port number): 

Socket connection = new Socket {hostname, portnum)-, 






Note: If you use sockets in an applet, you are still subject to the security restrictions 
about where you can connect. 



0 ncethesocket isopen, you can useinput and output streamsto read and writefrom that socket 
(you’ll learn all about input and output streams on Day 19): 

DatalnputStream in = new DataInputStream( 

new But fe red Input St ream (connect ion .getlnputStream ( ) ) ) ; 

DataOutputStream out= new DataOutputStream( 

new Buff e redOut putSt ream (connect ion . getOutputStream( ) ) ) ; 
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0 nceyou’redonewith thesocket, don’t forgetto closeit (thisalso closes all theinput and ouput 
streams you may have set up for that socket): 

connection .close ( ) ; 

Server-side sockets work similarly, with the exception of the accept o method. A server socket 
listens on a TC P port for a connection for a client; when a client connects to that port, the 
accept ( ) method acceptsaconnection from that client. By using both client and server sockets, 
you can create applications that communicate with each other over the network. 

T o create a server socket and bind it to a port, create a new instance of serversocket with the 
port number: 

ServerSocket sconnection = new ServerSocket (8888) ; 

T o listen on that port (and to accept a connection from any clients if one is made), use the 
accept o method: 

sconnection . accept ( ) ; 

0 nee thesocket connection ismade, you can useinput and output streams to read to and write 
from the client. 

Seethejava.net package for more information about Java sockets. 

Other Applet H ints 

On this, the last section of the last day of the second week, let'sfinish up with some small hints 
that didn’t fit in anywhere else: using showstatuso to print messages in the browser' status 
window, providing applet information, and communicating between multiple applets on the 
same page. 

The showStatus Method 

The showstatuso method, available in the applet class, enables you to display a string in the 
status bar of the browser, which contains the applet. You can use this for printing error, link, 
help, or other status messages: 

getAppletContext() .showStatus) "Change the color"); 

The getAppietcontext ( ) method enables your applet to access features of the browser that 
contains it. You already saw a use of this with links, wherein you could usetheshowDocumento 
method to tell thebrowserto load apage. showstatuso usesthatsamemechanism to print status 
messages. 
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Note: showstatuso may not be supported in all browsers, so do not depend on it 
for your applet’s functionality or interface. It is a useful way of communicating 
optional information to your user— if you need a more reliable method of commu- 
nication, set up a label in your applet and update it to reflect changes in its message. 



Applet I nformation 

T he AWT gives you a mechanism for associating information with your applet. U sually, there 
isa mechanism in the browser viewing theapplet to view display information. You can usethis 
mechanism to sign your name or your organization to your applet, or to provide contact 
information so that users can get hold of you if they want. 

T o provide information about your applet, override the getAppietmtoo method: 

public String getAppletInfo() { 

return "GetRaven copyright 1995 Laura Lemay"; 

> 

Communicating Between Applets 

Sometimesyou want to have an HTML page that has several different appletson it. To do this, 
all you have to do isincludeseveral different iterationsof theapplet tag — the browser will create 
different instances of your applet for each one that appears on the H T M L page. 

What if you want to communicate between those applets? What if you want a change in one 
applet to affect the other applets in someway? 

T he best way to do this is to use the applet context to get to different applets on the same page. 
You 'veal ready seen the use of the getAppietcontexto method for several other uses; you can 
also use it to get hold of the other applets on the page. F or example, to call a method in all the 
appletson a page (including the current applet), usethegetAppietso method and ator loop 
that looks something like this: 

for (Enumeration e = getAppletContext ( ) .getApplets() ; 
e.hasMoreElements() ; ) { 

Applet current = (Applet) (e. nextElement() ) ; 
sendMessage(current) ; 
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T hegetAppiets < ) method returnsan Enumeration object with a list of theappletson the page. 
Iterating over the Enumeration object in this way enables you to access each element in the 
Enumeration in turn. 



If you want to call a method in a specific applet, it'sslightly morecomplicated. To do this, you 
giveyourappletsanameandthen refer to them bynameinsidethebody of codeforthat applet. 

T o give an applet a name, use the name parameter in your HTM L file: 

<P>This applet sends information: 

<APPLET CODE="MyApplet. Class" WIDTH=100 HEIGHT=150 
NAME="sender"> </APPLET> 

<P>This applet receives information from the sender: 

<APPLET CODE="MyApplet. Class" WIDTH=100 HEIGHT=150 
NAME="receiver"> </APPLET> 

T o get a reference to another applet on the same page, use the getAppiet < > method from the 
applet context with thenameof that applet. Thisgivesyouareferencetotheapplet of that name. 
You can then refer to that applet as if it werejust another object: call methods, set its instance 
variables, and so on: 

// get ahold of the receiver applet 

Applet receiver = getAppletContext () .getAppiet ( "receiver" ) ; 

// tell it to update itself. 
reciever.update(text, value); 

I n this example, you usethegetAppiet < > method to get a reference to theapplet with thename 
receiver. G iven that reference, you can then call methods in that applet as if it werejust another 
object in yourown environment. H ere, for example, if both appletshavean updateo method, 
you can tell receiver to update itself by using the information the current applet has. 

N amingyour applets and then referring to them by using the methods described in thissection 
enables your applets to communicate and stay in sync with each other, providing uniform 
behavior for all the applets on your page. 

Summary 

C ongratulationsIT akeadeep breath— you’re finished with W eek 2. T hisweek has been full of 
useful information about creating applets and using thejava AWT classes to display, draw, 
animate, process input, and create fully fledged interfaces in your applets. 

T oday, you finished exploring applets and the AWT by learning about three concepts. 

First, you learned about windows, frames, menus, and dialogs, which enable you to create a 
framework for your applets- or enable your Java applications to take advantage of applet 
features. 

Second, you head a brief introduction to Java networking through some of the classes in the 
java.net package. Applet networking includes things as simple as pointing the browser to 
another pagefrominsideyour applet, but can also includeretrievingfilesfrom theW eb by using 





Windows, Networking, and Other Tidbits 



standard W eb protocols(http, ftp, and soon). Formoreadvanced networking capabilities, J ava 
provides basic socket interfaces that can be used to implement many basic network-oriented 
applets- client-server interactions, chat sessions, and so on. 

Finally, you finished up with the tidbits- small features of thej ava AWT and of applets that 
didn’t fit anywhere else, including showstatuso, producing information for your applet, and 
communicating between multiple applets on a single page. 

Q&A 

Q When I create popup windows using theappietviewer, they all show up with this 
big red bar that says warning: applet window. What does this mean? 

A Thewarningistotell you (and the users of your applet) that the window being 
displayed was generated by an applet, and not by the browser itself. T his is a security 
feature to keep an applet programmer from popping up awindow that masquerades as 
a browser window and, for example, asks users for their passwords. 

There's nothing you can do to hide or obscure the warning. 

Q What good is having a file dialog box if you can't read or write files from the 
local filesystem? 

A Applets can't read or write from the local filesystem, but because you can use AWT 
components in Java applications as well as applets, the file dialog box is very useful for 
that purpose. 

Q How can I mimic an HTML form submission in a Java applet? 

A Currently, applets make it difficult to do this. The best (and easiest way) is to use get 
notation to get the browser to submit the form contents for you. 

HTML forms can be submitted in two ways: by using the get request, or by using 
post. If you use get, your form information isencoded in theLIRL itself, something 
likethis: 

http: / /www. blah. com/cgi -bin /myscript?f oo=1 &bar=2&name=Laura 

Because the form input isencoded in theLIRL, you can write a Java applet to mimic a 
form, get input from the user, and then construct a new URL object with the form 
data included on the end. Then just pass that U RL to the browser by using 
getAppietcontext ( ) . showDocument ( ), and the browser will submit the form results 
itself. For simple forms, this is all you need. 



300 





Q H ow can I do post form submissions? 

A You’ll have to mimic what a browser does to send forms using post: open a socket to 
the server and send the data, which looks something likethis (the exact format is 
determined by the H TT P protocol; this is only a subset of it): 

POST /cgi-bin/mailto.cgi HTTP/1.0 

Content - type: application/ x-www-form-urlencoded 

Content -length: 36 

{your encoded form data here} 

I f you’ve done it right, you get the C G I form output back from the server. I t’s then up 
to your applet to handle that output properly. Note that if the output is in HTM L, 
there really isn’t a way to pass that output to the browser that is running your applet. 

If you get back a URL, however, you can redirect the browser to that URL. 

Q showstatus doesn't work in my browser. H ow can I give my readers status 
information? 

A As you learned in the section on showstatuso, whether or not a browser supports 
showstatus o is up to that browser. If you must have status-like behavior in your 
applet, consider creating a status label in the applet itself that is updated with the 
information you need to present. 
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Modifiers 



Once you begin to program Java for a while, you’ll discover that making all your classes, 
methods, and variables public can becomequiteannoying.Thelargeryourprogram becomes, 
andthemoreyou reuseyourdassesfor new projects, themoreyou will wantsomesort of control 
over their visibility. Oneof the large-scale solutionsto this problem, packages, must wait until 
tomorrow, but today you’ll explore what you can do within a class. 

T oday, you’ll learn how to create and use the following: 

□ il ethods and variables that control their access by other classes 
□t i lass variables and methods 

□ Constant variables, classes that cannot be subclassed, and methods that cannot be 
overridden 

□ Abstract classes and methods 

NE M odifi ers are prefixes that can be appl ied i n various combi nations to the methods and 
TERM variables within a class and, some, to the class itself. 

There is a long and varied list of modifiers. The order of modifiers is irrelevant to their 
meaning— your order can vary and is really a matter of taste. Pick a style and then be consistent 
with it throughout all your classes. H ere is the recommended order: 

<access> static abstract synchronized <unusual> final native 

where <access> can be public, protected, or private, and <unusuai> includes volatile and 
transient. 



Note: As of the beta release, threadsate has been replaced by volatile. Both have 
to do with multithreading; no more will be said about them here (see Day 18). 
transient is a special modifier used to declare a variable to be outside the persistent 
part of an object. T his makes persistent object storage systems easier to implement 
in Java, and though the compiler supports it, it is not used by the current Java 
system. Several reserved keywords (byvaiue, future, and generic, for example) may 
end up being <unusuai> modifiers in later releases of Java. In the beta system, none 
of these unusual modifiers appears in the source code for the standard J ava library 
classes. 



All the modifiers are essentially optional; none have to appear in a declaration. Good style 
suggests adding as many as are needed to best describe the intended useof, and restrictions on, 
what you’redeclaring. In some special situations (inside an interface, for example, asdescri bed 
tomorrow), certain modifiers areimplicitly defined for you, and you needn't type them— they 
will be assumed to be there. 
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T hesynchronized modifier is covered on D ay 18; it hasto do with multithreaded methods. T he 
native modifier is covered on Day 20; it specifiesthat a method is implemented in the native 
language of your computer (usually C), rather than in Java. How <access> modifiers apply to 
classes is covered tomorrow. 

Method and Variable Access Control 

Access control is about controlling visibility. When a method or variable is visible to another 
class, itsmethodscan reference (cal I or modify) that method or variable. T o "protect" a method 
or variable from such references, you use the four levels of visibility described in the next 
sections. Each, in turn, is more restrictive, and thus provides more protection than the one 
before it. 

T he F our P 's of P rotection 

Learningyourfour P’s(pubiic, package, protected, and private) comesdown to understanding 
the fundamental relationships that a method or variable within a class can have to the other 
classes in the system. 

public 

Because anydassisan island unto itself, thefirst of theserelationshipsbuildson thedistinction 
between the inside and the outsideof thedass. Any method or variable is visibleto the class in 
which it isdefined, but what if you want to make it visibleto all the classes outside this class? 

Theanswerisobvious: simply dedarethemethodorvariabletohavepubiic access. Almost every 
method and variable defined in the rest of this book has been declared, for simplicity’s sake, 
public. W hen you use any of the examples provided in your own code, you’ll probably decide 
to restrict thisaccessfurther. Because you’rejust learning now, it’snot a bad idea to begin with 
the widest possible access you can imagine and then narrow it down as you gain design 
experience, until theaccessthat each of yourvariablesand methodsshould havebecomessecond 
nature. H ere are some examples of public declarations: 

public class APublicClass { 
public int aPublicInt; 
public String aPublicString; 

public float aPublicMethod() { 

} 

> 
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N ote: T he two (or more) spaces after the prefix of modifiers and type i n these 
declarations are intentional. T hey make finding the variable or method name 
within each line a little easier. Further in the book, you’ll see that the type and the 
name are sometimes separately lined up in a column to make it even more evident 
what is what. When you get enough modifiers on aline, you’ll begin to appreciate 
these small touches. 



A variable or method with public access has the widest possible visibility. Anyone can see it. 
Anyone can use it. Of course, this may not always be what you want— which brings us to the 
next level of protection. 



package 

In C, there is the notion of hiding a nameso that only the functionswithin a given source file 
can see it. I n J ava, source files are replaced by the more explicit notion of packages, which can 
group classes (you learn about these tomorrow). For now, all you need to know is that the 
relationship you want to support isofaclass to itsfellow implementors of onepiece of asystem, 
library, or program (or to any other grouping of related classes). This defines the next level of 
increased protection and narrowed visibility. 

D ue to an idiosyncrasy of the J ava language, this next level of access has no precise name. 1 1 is 
indicated by the lack of any access modifier in a declaration. FI istori cally, it has been called 
various suggestive names, including "friendly” and "package.” The latter usage seems most 
appropriate and istheoneused here. Perhaps in a later release of the system, it will be possible 
to say package explicitly, but for now it is simply the default protection when none has been 
specified. 



Note: Why would anyone want to make more typing for themselves and explicitly 
say package? It is a matta of consistency and clarity. If you have a pattern of 
declarations with varying access modifier prefixes, you may always want the 
modifier to be stated explicitly, both for the reader's benefit and because, in some 
contexts, different "default” levels of protection are being assumed, and you want 
the compiler to notice your intentions and warn you of any conflicts. 
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M ost of the declarations you've seen in the past two weeks have used this default level of 
protection. H ere’s a reminder of what they look like: 

public class ALessPublicClass { 
int aPackagelnt = 2; 

String aPackageString = “a 1 and a 

float aPackageMethod() { // no access modifier means "package" 



> 

public class AClasslnTheSamePackage { 
public void testUse() { 

ALessPublicClass aLPC = new ALessPublicClass () ; 

System. out. println(aLPC. aPackageString + aLPC. aPackagelnt) ; 
aLPC.aPackageMethod() ; // all of these are A.O.K. 

} 

> 



N ote: I f a class from any other package tried to access aLPC the way that 
AciassimhesamePackage doesin this example, it would generate compile-time 
errors. (You’ll learn how to create such classes tomorrow.) 



W hy was package madea default? W hen you’re designing a large system and you partition your 
classes into work groups to implement smaller pieces of that system, the classes often need to 
sharea lot morewith one another than with theoutsideworld. T heneed for this level of sharing 
is common enough that it was made the default level of protection. 

What if you have some detailsof your implementation that you don’t want to share with these 
"friends"? T he answer to this question leads us naturally to the next level of protection. 



protected 

Thethird relationship is between a class and its present and future subclasses. These subclasses 
are much closer to a parent class than to any other "outside" classes for the following reasons: 

□ Subclasses are usually more intimately aware of the internals of a parent class. 

□ Subclasses are often written by you or by someone to whom you’ve given your source 
code. 

. Subclasses frequently need to modify or enhance the representation of the data within 
a parent class. 
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N o one else is allowed the privilege of this level of access; they must be content with the public 
face that the class presents. 

To support the level of intimacy reserved for subclasses, modern programming languages have 
invented an intermediate level of access between the previous two levelsand full privacy. This 
level gives more protection and narrows visibility still further, but still allows subclasses full 
access. In Java, this level of protection is called, appropriately enough, protected: 

public class AProtectedClass { 

protected int aProtectedlnt = 4; 

protected String aProtectedString = "and a 3 and a 

protected float aProtectedMethod( ) { 

} 

} 

public class AProtectedClassSubclass extends AProtectedClass { 
public void testUse() { 

AProtectedClass aPC = new AProtectedClass () ; 

System. out. println(aPC. aProtectedString + aPC.aProtectedlnt); 
aPC.aProtectedMethod( ) ; // all of these are A.O.K. 

} 

> 

public class AnyClasslnTheSamePackage { 
public void testUse() { 

AProtectedClass aPC = new AProtectedClass () ; 

System. out. println(aPC. aProtectedString + aPC.aProtectedlnt); 
aPC.aProtectedMethod( ) ; // NONE of these are legal 



Even though AnyClasslnTheSamePackage is in the Same package as AProtectedClass, it is not a 
subclass of it (it’s a subclass of object). 0 nly subclasses are allowed to see, and use, protected 
variables and methods. 

One of the most striking examples of the need for this special level of access is when you are 
supportingapublicabstractionwithyourclass.Asfarastheoutsideworldisconcerned,you have 
a simple, public interface (via methods) to whatever abstraction you’ve built for your users. A 
more complex representation, and the implementation that depends on it, is hidden inside. 
When subclasses extend and modify this representation, or even just your implementation of 
it, they need to get to the underlying, concrete representation and not simply to the abstraction: 

public class SortedList { 

protected BinaryTree theBinaryTree; 



public Objectj] theList() { 

return theBinaryTree. asArrayO ; 
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public void add(Object o) { 
theBinaryTree.addObject(o) ; 



> 

public class InsertSortedList extends SortedList { 
public void insert (Object o, int position) { 
theBinaryTree.insertObject(o, position) ; 

} 

> 

W ithout being ableto access theBinarymee directly, the insert ( > method has to get the list as 
an array of objects, viathepublic method theListo,allocatea new, bigger array, and insert the 
new object by hand. By "seeing" that its parent is using a BinaryTree to implement the sorted 
list, it can call upon BinaryTree’s built-in method msertobjecto to get thejob done. 

Some languages, such as C LU , have experimented with more explicit ways of "raising” and 
"lowering" your level of abstraction to solve this same problem in a more general way. In Java, 
protected solves only a part of the problem, by allowing you to separate the concrete from the 
abstract; the rest is up to you. 



private 

Thefinal relationship comes full circle, back to the distinction between the inside and outside 
of the class, private isthemost narrowly visible, highest level of protection that you can get — 
the diametric opposite of public, private methods and variables cannot be seen by any class 
other than the one in which they are defined: 

public class APrivateClass { 
private int aPrivatelnt; 
private String aPrivateString; 

private float aPrivateMethod() { 



T hismay seem extremely restrictive, but it is, in fact, a commonly used level of protection. Any 
privatedata, internal state, or representations uniqueto your implementation— anything that 
shouldn’t bedirectly shared with subclasses- isprivate. Remember that an an object’sprimary 
job isto encapsulate its data— to hide it from the world’s sight and limit its manipulation. The 
best way to do that isto make as much data as private as possible. Your methodscan always be 
less restrictive, as you’ll see below, but keeping a tight rein on your internal representation is 
important. It separates design from implementation, minimizestheamount of information one 
class needsto know about another to getitsjobdone,andreducestheextentofthecodechanges 
you need when your representation changes. 
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The Conventions 

for I nstance Variable Access 



A good ruleof thumb isthat unlessan instance vari abl e i scon stant (you’ll soon seehow to specify 
this), it should almost certainly beprivate. If you don’t do this, you havethefol lowing problem: 

public class AFoolishClass { 

public String aUsefulString; 

... // set up the useful value of the string 

> 

T his class may have thought of setting up ausef uistring for the use of other classes, expecting 
them to (only) read it. Because it isn’t private, however, they can say: 

AFoolishClass aFC = new AFoolishClass ( ) ; 



aFC. aUsefulString = "oops!"; 

Because thereisno way to specify separately thelevel of protection for reading from and writing 
to instance variables, they should almost always be private. 



Note: The careful reader may notice that this rule is violated in many examples in 
thisbook. M ost of these werejust for clarity’s sake and to make the examples 
shorter and pithier. (You’ll see soon that it takes more space to do the right thing.) 
One use cannot be avoided: the system, out. print o calls scattered throughout the 
book must use the public variable out directly. You cannot change this final 
system class (which you might have written differently). You can imagine the 
disastrous results if anyone accidentally modifies the contents of this (global) 
public variable! 



Accessor Methods 

If instance variables are private, how do you give access to them to the outside world? The 
answer is to write "accessor” methods: 

public class ACorrectClass { 

private String aUsefulString; 

public String aUsefulString () { // "get” the value 

return aUsefulString; 

} 

protected void aUsefulString(String s) { // "set" the value 

aUsefulString = s; 
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U sing methodsto access an instance variableisoneofthemost frequently used idiomsin object- 
oriented programs. Applying it liberally throughout all your classes repaysyou numeroustimes 
over with more robust and reusable programs. N otice how separating the reading and writing 
of theinstancevariableallowsyou to specify a public method to return itsvalueand aprotected 
method to set it. Thisisoften a useful pattern of protections, because everyone probably needs 
to be able to ask for the value, but only you (and your subclasses) should beableto change it. 
If it isa particularly privatepiece of data, you could makeits"set” method private and its "get" 
method protected, or any other combination that suits the data’s sensitivity to the light of the 
outside world. 





Warning: According to the beta language specification, it is not legal to have an 
instance variable and method by the same name. H owever, the beta compiler allows 
it! Because it is unclear what the final ruling on this conflict will be, use the simple 
naming scheme used previously for your programs. In a lata release, if the compiler 
begins complaining, you can always change the method names to something less 
clear. 



0 ne of the alternate conventions for the naming of accessor methods is to prepend 
the variable name with the prefixes get and set. Besides making you type more- 
fora little lessdarity— this style forces you (by the capitalization conventions of 
J ava) to write methods names such as setAnnoyingFirstCapitalLetter ( ) . All this is, 
of course, amatta of taste- just be consistent in using whateva convention you 
adopt. 



W henever you want to append to your own instance variable, try writing this: 

aUsefulString(aUsefulString() + " some appended text"); 

Just like someone outside the class, you’re using accessor methodsto change ausefuistring. 
Why do this? 

You protected thevariablein the first place so that changes to your representation would not 
affect the use of you r cl ass by others, but it sti 1 1 wi 1 1 affect the u se of you r cl ass by you ! As i n the 
abstract vasus concrete discussion earlier, you should be protected from knowing too much 
about your own representation, except in those few places that actually need to know about it. 
T hen, if you must change something about ausefuistring, it will not affect evay use of that 
variable in your class (as it would without accessor methods); ratha, it affects only the 
implementations of its accessor. 
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Oneof the powerful si d e effects of maintaining this level of indirection in accessing your own 
instancevariablesisthatif, atsomelater date, somespecial codeneedsto be performed each time 
auset uistring isaccessed, you can put that codein oneplace, and all theother methodsin your 
class (and in everyone else's) will correctly call that special code. H ere's an example: 

protected void aUsef uistring (String s) { // the "set" method 

aUsefulString = s; 

performSomelmportantBookkeepingOn(s) ; 

> 

It may seem a little difficult to get used to saying this: 

x (12 + 5 * x() ) ; 

rather than this: 

x = 12 + 5 * x; 

but the minor inconvenience will reward you with a rosy future of reusability and easy 
maintenance. 

Class Variables and Methods 

W hat if you want to create a shared variable that all your instances can see and use? I f you use 
an in stance variable, each instance has its own copy of thevariable, defeating its whole purpose. 
If you placeit in the class itself, however, thereisonly onecopy, and all the instances of thedass 
share it. T his is called a class variable: 

public class Circle { 

public static float pi = 3.14159265F; 

public float area(float r) { 
return pi * r * r; 



X Tip: Because of its historical ties, J ava uses the word static to declare class vari- 
ables and methods. W henever you see the word static, remember to substitute 
w mentally the word "class." 

Instances can refer to their own class variables as though they were instance variables, as in the 
last example. Because it’s public, methodsin other classes can also refer to pi: 

float circumference = 2 * Circle. pi * r; 
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N ote: I nstances of circle can also use this form of access. I n most cases, for clarity, 
this is the preferred form, even for instances. It clarifies that a class variable is being 
used, and helps the reader to know instantly where it’s used and that the variable is 
global to all instances. This may seem pedantic, but if you try it yourself, you’ll see 
that it can make things clearer. 

By the way, if you might change your mind later about how a class variable is 
accessed, created, and so forth, you should create instance (or even class) accessor 
methods to hide any uses of it from these changes. 



Classmethodsaredefinedanalogously.Theycanbe accessed i n th e same two ways by i n stan ces 
of their class, but only via the full class name by instances of other classes. H ere’s a class that 
defines cl ass methods to help it count its own instances: 

public class instanceCounter { 

private static int instanceCount = 0; //a class variable 

protected static int instanceCount () { //a class method 

return instanceCount; 

} 

private static void incrementCount() { 

++instanceCount; 

> 

InstanceCounter( ) { 

InstanceCounter. incrementCount ( ) ; 



In this example, an explicit use of the class name calls the method incrementCount o. Though 
thismayseem verbose, in alargerprogramitimmediatelytellsthereaderwhich object (thedass, 
rather than theinstance) isexpected to handlethemethod. T hisisespeci ally useful if thereader 
needsto find where that method isdedared in a large class that places all itsdassmethodsatthe 
top (the recommended practice, by the way). 

N ote the initialization of instanceCount to 0. J ust as an instance variable is initialized when its 
instanceiscreated, a class variable is initialized when itsclassiscreated. T hisclassinitialization 
happensessentially before anything else can happen to that class, or its instances, so the class in 
the example will work as planned. 

Finally, theconventionsyou learned for accessingan i n stan cevariableareapplied in thisexample 
to access a class variable. T he accessor methods are therefore class methods. (T here is no "set" 
method here, just an increment method, because no one is allowed to set instanceCount 
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directly.) Note that only subclasses are allowed to ask what the mstancecount is, because that 
is a (relatively) intimate detail. H ere’satest of instancecounter in action: 

public class instanceCounterTester extends Instancecounter { 
public static void main(String args[]) { 
for (int i = 0; i < 10; ++i) 

new InstanceCounter() ; 

System. out. println( "made “ + Instancecounter. instanceCount() ) ; 



N ot shockingly, this example prints the following: 

made 10 

The final Modifier 

Although it’s not the final modifier discussed, the final modifier is very versatile: 

Z When the final modifier is applied to a class, it means that the class cannot be 
subclassed. 

Z When it is applied to a variable, it means that the variable is constant. 

Z W hen it is applied to a method, it means that the method cannot be overridden by 
subclasses. 



final Classes 

H ere’safinai class declaration: 

public final class AFinalClass { 



Youdeclareaclassfinaiforonlytwo reasons. T hefirst issecurity. You expecttouseitsinstances 
asunforgeablecapabilities, and you don't want anyoneelse to beableto subclass and createnew 
and different instancesofthem.Thesecond isefficiency. You want to count on instancesof only 
that onedass(and no subclasses) being around in the system so that you canoptimizeforthem. 



Note: The Java cl ass library uses final classes extensively. You can flip through the 
class hierarchy diagrams in Appendix B to see them (final classes are shaded darker 
than public classes). Examples of the first reason to use final are the classes: 
java.lang. System and, from the package java.net, inetAddress and Socket. A 
good example of the second reason is java.lang. string. Strings are so common in 
J ava, and so central to it, that the run-time handles them specially. 
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It will be a rare event for you to create a final class yourself, although you’ll have plenty of 
opportunity to be upset at certain system classes being final (thus making extending them 
annoyingly difficult). 0 h well, such is the price of security and efficiency. Let’s hope that 
efficiency will belessof an issuesoon, and some of these classes will becomepubiic once again. 



final Variables 

T o declare constants in J ava, use final variables: 

public class AnotherFinalClass { 

public static final int aConstantlnt = 123; 

public final String aConstantString = “Hello world!"; 



N ote: T he unusual spacing in the last line of the example makes it clearer that the 
top variable is a class variable and the bottom isn’t, but that both are public and 



final class and in stance variables can be used in expressionsjust like normal class and instance 
variables, but they cannot bemodified. Asaresult, final variablesmustbegiven their (constant) 
value at the time of declaration. These variables function like a better, typed version of the 
#def me constants of C . C lasses can provide useful constants to other classes via final class 
variables such as the one discussed previously. Other classes reference them just as before: 

AnotherFinalClass . aConstantlnt. 

Local variables (those inside blocks of code surrounded by braces, for example, in while or for 
loops) can't bedeclared final. (T hiswould bejust aconvenience, really, becausef mai instance 
variableswork almost as well inthiscase.) Infact, local variables can haveno modifiers in front 
of them at all: 

{ 

int aLocalVariable; // I'm so sad without my modifiers... 



final Methods 

H ere’s an example of using final methods: 

public class MyPenultimateFinalClass { 

public static final void aUniqueAndReallyUsefulMethod() { 

} 
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public final void noOneGetsToDoThisButMe() { 

} 

> 

final methods cannot be overridden by subclasses. It isa rare thing that a method truly wants 
to declare itself the final word on its own implementation, so why does this modifier apply to 
methods? 

The answer isefficiency. If you declare a method final, thecompiler can then "in-line" it right 
in the middle of methods that call it, because it "knows" that no one else can ever subclass and 
overridethe method to changeitsmeaning. Although you might not usef inai right away when 
writing adass, asyou tunethesystem later, you may discover that afew methodshaveto bef mai 
to makeyour class fast enough. Almost all yourmethodswill be fine, however, just as they are. 

T hej ava class library declaresa lot of commonly used methodsf mai so that you’ll benefit from 
thespeed-up. In thecaseof dassesthat are already final, thismakes perfect sense and isa wise 
choice. Thefew final methods declared in non-fmai classes will annoy you— your subclasses 
can no longer overridethem. When efficiency becomeslessof an issuefor thej ava environment, 
many of these 
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Note: Futurejava compilers will almost certainly be smart enough to "in-line" 
simple methods automatically, so you probably won’t need to use final in such 
cases for much longer. 



abstract Methods and Classes 

Whenever you arrange classes into an inheritance hierarchy, the presumption isthat "higher" 
classes aremore abstract and general, whereas “lower" subclasses are more concrete and specific. 
Often, as you design a set of classes, you factor out common design and implementation into 
a shared superclass. If theprimary reason that a superclass exists is to act asthiscommon, shared 
repository, and if only itssubdasses expect to be used, that superclass is cal led an abstract class. 

abstract classes can create no instances, but they can contain anything a normal class can 
contain and, in addition, areallowed to prefixany of their methodswith themodifier abstract. 
N on-abstract classes arenot allowed to usethis modifier; using it on even oneof your methods 
requires that your whole class be declared abstract. H ere’s an example: 

public abstract class MyFirstAbstractClass { 
int anlnstanceVariable; 



} 



public abstract int aMethodMyNonAbstractSubclassesMustImplement( ) ; 

public void doSomethingO { 

... //a normal method 



} 



public class AConcreteSubClass extends MyFirstAbstractClass { 
public int aMethodMyNonAbstractSubclassesMustImplement( ) { 

... //we *must* implement this method 

> 

> 

and some attempted uses of these classes: 

Object a = new MyFirstAbstractClass ( ) ; // illegal, is abstract 

Object c = new AConcreteSubClass () ; // OK, a concrete subclass 

N otice that abstract methods need no implementation; it is required that non-abstract 
subclasses providean implementation. T he abstract class simply provides thetemplate for the 
methods, which are implemented by others later. I n fact, in thej ava cl ass library, thereareseveral 
abstract classes that have no documented subclasses in the system, but simply provide a base 
from which you can subclass in your own programs. If you look at the diagrams in Appendix 
B, abstract classes are shaded even darker than final classes and are quite common in the 
library. 
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U sing an abstract class to embody a puredesign- that is, nothing but abstract methods- is 
better accomplished inj ava by usingan interface(discussed tomorrow). W hen everadesign calls 
for an abstraction that includes instance state and/or a partial implementation, however, an 
abstract class isyour only choice. I n previous object-oriented languages, abstract classes were 
simply a convention. They proved so valuable that Java supports them not only in the form 
described here, but in the purer, richer form of interfaces, which will be described tomorrow. 

Summary 

T oday, you learned how variables and methods can control their visibility and access by other 
classes viathefour P'sof protection: public, package, protected, and private. You also learned 
that, although instance variables are most often declared private, declaring accessor methods 
allows you to control the reading and writing of them separately. Protection levels allow you, 
for example, to separate cleanly your public abstractions from their concrete representations. 

You also learned how to create class variables and methods, which are associated with the class 
itself, and how to declare final variables, methods, and classes to represent constants, fast or 
secure methods, and classes, respectively. 

Finally, you discovered how to declare and use abstract classes, which cannot be instantiated, 
and abstract methods, which have no implementation and must be overridden in subclasses. 
T ogether, they provide a template for subclasses to fill in and act as a variant of the powerful 
interfaces of Java that you’ll study tomorrow. 

Q&A 

Q W hy are there so many different levels of protection in J ava? 

A Each level of protection, or visibility, provides a different view of your class to the 
outside world. One view is tailored for everyone, one for classes in your own package, 
another for your class and its subclasses only, and thefinal onefor just within your 
class. Each is a logically well-defined and useful separation that Java supports directly 
in the language (as opposed to, for example, accessor methods, which are a convention 
you must follow). 

Q Won't using accessor methods everywhere slow down my Java code? 

A N ot always. Soon, Java compilers will be smart enough to make them fast automati- 
cally, but if you’re concerned about speed, you can always declare accessor methods to 
be final, and they’ll be just as fast as direct instance variable accesses. 
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Q Are class (static) methods inherited just like instance methods? 

A Yes, and no. The beta compiler still allows you to inherit them, but according to one 
of the oddest changes in the beta language specifications, static (class) methods are 
now final by default. H ow, then, can you ever declare a non-finai class method? The 
answer is that you can’t! I nheritance of class methods is not allowed, breaking the 
symmetry with instance methods. Because this goes against a part of Java’s philosophy 
(of making everything as simple as possible) perhaps it will be reversed in a lata 
release. For now, follow thecompila and assume that class methods are inherited 
normally. 

Q Based on what I 've learned, it seems like final abstract or private abstract 
methods or classes don’t make sense. Are they legal? 

A N ope, they’re compile-time arors, as you have guessed. T o be useful, abstract 
methods must be overridden, and abstract classes must be subclassed, but neithaof 
those two opaations would be legal if they were also public or final. 

Q What about static transient or final transient? 

A T hose are also compile-time arors. Because a "transient” part of an object’s state is 
assumed to be changing within each instance, it can not be static or final. This 
restriction mattasonly in thefuture, though, when transient is actually used byjava. 
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When you examine a new language feature, you should ask yourself two questions: 

1. H ow can I use it to better organize the methods and classes of my J ava program? 

2. How can I useitwhilewritingthejavacodein my methods? 

The first i s often called programming in thelarge, and the second, programming in thesmall. 
Billjoy, a founder of Sun M icrosystems, I ikes to say that Java feels like C when programming 
in thesmall and like Smalltalk when programming in thelarge. What he means by that isthat 
Java is familiar and powerful like any C-like language while you’re coding, but has the 
extensibility and expressive power of apureobject-oriented languagelikeSmalltalk whileyou're 
designing. 

The separation of "designing" from "coding” was one of the most fundamental advances in 
programming in the past few decades, and object-oriented languages such asj ava implement a 
strong form of this separation. The first part of this separation has already been described on 
previousdays: when you develop ajava program, first you design the classes and decideon the 
relationships between these classes, and then you implement thej ava code needed for each of 
themethodsin your design. If you are careful enough with both these processes, you can change 
your mind about aspectsof thedesign without affecting anything but small, local pieces of your 
Java code, and you can change the implementation of any method without affecting the rest of 
thedesign. 

Asyou begin to exploremoreadvanced Java programming, however, you’ll find that thissimple 
model becomes too limiting. T oday, you’ll explore these limitations, for programming in the 
large and in thesmall, to motivatetheneed for packages and interfaces. Let’s start with packages. 

Packages 

Packages are Java’s way of doing large-scale design and organization. They are used both to 
categorize and group classes. Let’s explore why you might need to use packages. 

Programming in the Large 

W hen you begin to develop J ava programs that use a large number of classes, you will quickly 
discover some limitations in the model presented thusfar for designing and building them. 

Foronething, asthenumber of classes you build grows, the likelihood of your wanting to reuse 
the short, simplenameof some class increases. If you use classes that you’ve built in the past, 
or that someone else has built for you (such as the classes in the Java library), you may not 
remember— or even know— that these class names are in conflict. Being able to "hide” adass 
inside a package becomes useful. 
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H ere's a simple example of the creation of apackagein ajava source file: 

package myFirstPackage; 

public class MyPublicClass extends itsSuperclass { 

> 



Note: If a package statement appears in ajava source file, it must be the first thing 
in that file (except for comments and white space, of course). 



You first declare the name of the package by usi ng a package statement. T hen you defi ne a class, 
just as you would normally. That class, and any other classes also declared inside this same 
package name, are grouped together. (These other classes are usually located in other, separate 
source files.) 

Packages can be further organized into a hierarchy somewhat analogous to the inheritance 
hierarchy, whereeach "level" usually represents a smaller, morespecific grouping of classes. The 
J ava class library itself isorganized along these lines (see thediagrams in Appendix B). The top 
level iscalled java; thenext level includes names such asio, net, utn, and awt. Thelast has an 
even lower level, which indudesthepackageimage. T hecoiorModei class, located in thepackage 
image, can be uniquely referred to anywhere in your J ava code as j ava . awt . image . coiorModei. 



Note: By convention, the first level of the hierarchy specifiesthe (globally unique) 
name of the company that developed the Java packaged). For example, Sun 
M icrosystem's classes, which are not part of the standard J ava environment, all 
begin with the prefix sun. The standard package, java, is an exception to this rule 
because it is so fundamental and because it might someday be implemented by 
multiple companies. 

Starting with the beta release, Sun has specified a more formal procedure for 
package naming to be followed in the future. The top-level package name space 
now reserves, for the use of this procedure, all the uppercase abbreviations used for 
top-level domains on the Internet (ED U, COM , GOV, FR, US, and so on). These 
reserved names form thefirst part of all new package names, which are prefixed by 
a reversed version of your domain name. By this procedure, the sun packages would 
be called com. sun. If you’re further down in your company’s or university’s domain 
tree, you can keep reversing to your heart's content: 

EDU . harvard . cs . projects . ai . learning . myPackage. Because domain names are 

already guaranteed to be unique globally, this nicely solves that thorny problem, 
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I and as a bonus, the applets and packages from the potentially millions of Java 

programmers out there will automatically be stored into a growing hierarchy below 
your classes directory, giving you away to find and categorize them all in a 
comprehensible manner. 



Because each Java class should be located in a separate source file, the grouping of classes 
provided by a hierarchy of packages is analogous to the grouping of files into a hierarchy of 
directories on your file system. Thejava compiler reinforces this analogy by requiring you to 
createadirectory hierarchy under yourcl asses directory that exactly matchesthehierarchy of the 
packagesyou havecreated,andto pi ace a cl ass into thedirectory with thesamename(and level) 
as the package in which it’s defined. 

For example, the directory hierarchy for thejava class library exactly mirrors its package 

hierarchy. 0 n U N I X , for example, thedass referenced as j ava . awt . image . coioriviodei isstored 

inafilenamedColorM odel.classin thedirectory named .../classes/java/awt/image(the...isthe 

path wherej ava was installed on your computer). I n particular, if you have created a package 

within myFirstPackage called mysecondPackage, by declaring a class: 

package myFirstPackage . mySecondPackage ; 

public class AnotherPublicClass extends AnotherSuperclass { 



thej ava source file (called A n otherP u bl i cC I ass.j ava) must be located in a directory below the 
current directory called dasse^myFirstPackage/mySecondPackage for the compiler (javac) to 
find it. W hen thecompiler generates thefileAnotherPublicC lass.class, it placesit into thissame 
directory so that thejava interpreter can find it. Both thecompiler and the interpreter expect 
(and enforce) the hierarchy. 



Note: This also means that, for today’s first example, the source file would be 
named APublicC lass.java and located in thedirectory called classes/ 
myFirstPackage. What happens when, as in earlier examples in the book, classes are 
defined without a package statement? T he compiler places such classes in a default, 
unnamed package, and their .java and .class files can be located in the current 
directory or in the classes directory below it. 

T o be more precise, any occurrence of the phrase "the current directory" in this 
section should be replaced by “any of the directories listed in the class path.” The 
compiler and interpreter both search this list of paths to find any classes you 
reference. 
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I You can specify a class path on the command line when runningjavacorjava, or 
more permanently, by changing a special environment variable called 
CLASSPATH . (For more details, read the documentation in yourjava release.) 



Programming in the Small 

When you refer to a class by name in yourjava code, you are using a package. M ost ofthetime 
you aren't aware of it because many of the most commonly used classes in the system are in a 
package that the Java compiler automatically imports for you, called java.iang. So whenever 
you saw this, for example: 

String aString; 

something more interesting than you might have thought was occurring. What if you want to 
refer to thedassyou created at the start of thissection, theonein thepackagemyFirstPackage? 
If you try this: 

MyPublicClass someName; 

the compiler complains- thedassMyPubiicciass is not defined in the package java.iang. To 
solve thisproblem, Java allows any dassnameto beprefixed by thenameofthepackagein which 
it was defined to form a unique reference to the class: 

myFirst Package . MyPublicClass someName ; 



N ote: Recall that by convention, package names tend to begin with a lowercase 
letter to distinguish them from class names. Thus, for example, in the full name of 
the built-in string class, java.iang. string, it’seasierto separate the package name 
from the class name visually. 



Suppose you want to use a lot of classes from a package, a package with a long name, or both. 
You don’t want to have to refer to you r classes as that . really . long . package . name . ClassName. 
J ava al I ows you to " i m port” the names of those classes i nto you r program .Theythenactjustas 
j ava . lang classes do, and you can refer to them without a prefix. F or example, to use the really 
long class name in the last example more easily, you can write the following: 

import that . really . long . package . name . ClassName ; 

ClassName anObject; 

// and you can use ClassName directly as many times as you like 
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Note: All import statements must appear after any package statement but before 
any class definitions. Thus, they are "stuck” at the top of your source file. 



W hat if you want to use several classesfrom that same package? H ere'san attempt from a (soon- 
to-be-tired) programmer: 

that . really .long . package. name .ClassOne first; 
that . really . long . package . name . ClassTwo second ; 

that . really . long . package . name . ClassThree andSoOn ; 

H ere'sonefrom amoresawy programmer, who knowshow to import a whole package of public 
classes: 

import that . really . long . package . name . * ; 

ClassOne first; 

ClassTwo second; 

ClassThree andSoOn; 

% 

Warning: The asterisk (*) in this example is not exactly the one you might use at a 
wQ command prompt to specify the contents of a directory. For example, if you ask to 
^ list the contents of the directory classe^java/awt/*, that list includes all the .class 

files and subdirectories such asimageand peer. Writing import java.awt.* doesnot 
import subpackages such as image and peer. T o import all the classes in a complex 
package hierarchy, you must explicitly import each level of the hierarchy by hand. 



If you plan to useadassorapackageonlyafewtimesin your sourcefile, it’sprobably not worth 
importing it. The rule of thumb is to ask yourself: "Does the loss in clarity I’d introduce by 
referring to just the class name outweigh the convenience of not having to type the extra 
characters?” If it does, don’t use import. Remember that the package name letsthe reader know 
whereto find more information about the class right at the place you're using it, rather than at 
the top of thefile, where the import statements are located. 

What if you have the following in dassA'ssourcefile? 

package packageA; 
public class ClassName { 

> 

public class ClassA { 

) 
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and in class B'ssourcefileyou have this: 

package packageB; 
public class ClassName { 

> 

public class ClassB { 

> 

Then you the write the following, somewhere else: 

import packageA; 
import packageB; 

ClassName anObject; // which ClassName did you mean? 

There are two possible interpretations for the class you intended, onein packageA and onein 
packageB. Because this is ambiguous, what should the poor compiler do? It generates an error, 
of course, and you have to bemore explicit about which oneyou intended. H ere'san example: 

import packageA.*; 
import packageB.*; 

packageA. ClassName anObject; // now OK 

packageB. ClassName anotherObject; // also OK 

ClassA anAObject; // was never a problem 

ClassB aBObject; // ditto 



Note: You may wonder about the numerous declarations that appear as examples 
in today’s lesson. Declarations are good examples because they’re the simplest 
possible way of referencing a class name. Any use of a class name (in your extends 
clause, for example, or in new ciassNameo) obeys the same rules. 



Hiding Classes 

The astute reader may have noticed that the discussion of importing with an asterisk (*) stated 
that it imported a whole package of public classes. W hy would you want to have classes of any 
other kind?T ake a look at this: 

package collections; 



public class LinkedList { 
private Node root; 
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public void add (Object o) { 
root = new Node(o, root); 

} 



class Node { // not public 

private Object contents; 
private Node next; 

Node(Object o, Node n) { 
contents = o; 
next = n; 

} 



Note: If this were all in one file, you might be violating one of the compiler’s 
conventions: only one class should be located in each Java source file. Actually, the 
compiler cares only about every public class being in a separate file (although it still 
isgood styleto use separate files for each class). 



The goal oftheLinkedList class isto provideaset of useful public methods (such asaddo) to 
any other classes that might want to use them. T hese other classes could care less about any 
support classes LinkedList needs to get its job done, and would prefer to not "see” them when 
using LinkedList. In addition, LinkedList may feel that the Node class is local to its implemen- 
tation and should not be seen by any other classes. 

For methods and variables, this would be addressed by the four Ps of protection discussed 
yesterday: private, protected, package, and public, listed in order of increasing visibility. 
You’ve already explored many public classes, and because both private and protected really 
make sense only when you’re inside a class definition, you cannot put them outside of one as 
part of defining anew class. LinkedList might really like to say "only classes in my source file 
can seethisdass," but because, by convention, each class is located in a separate source file, this 
would be a little-needed, over-narrow approach. 

I nstead, LinkedList dedaresno protection modifier, which isequivalentto sayingpackage. N ow 
thedasscan be seen and used only by other dassesin the same package in which it wasdefined. 
In thiscase, it’s the collections package. You might use LinkedList as follows: 

import collections.*; // only imports public classes 

LinkedList aLinkedList; 

/* Node n; */ // would generate a compile-time error 

aLinkedList .add (new lnteger(l 138) ) ; 
aLinkedList. addC'THX-' 1 ) ; 
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Note: You also can import or declare a LinkedList as collections. LinkedList in 
this example. Because LinkedList refers to Node, that class is automatically loaded 
and used, and the compiler verifies that LinkedList (as part of package collec- 
tions) has the right to create and use the Node class. You still do not have that right, 
though, just as in the example. 



0 ne of the great powers of hidden classes is that even if you use them to i ntroduce a great deal 
of complexity into the implementation of somepubiic class, all the complexity is hidden when 
that class is imported. Thus, creating a good package consists of defining a small, clean set of 
public classes and methodsfor other dassesto use, and then implementing them by using any 
number of hidden (package) support classes. You’ll see another usefor hidden dasseslatertoday. 



I nterfaces 

I nterfaces, liketheabstractdassesand methodsyou saw yesterday, providetemplatesof behavior 
that other classes are expected to implement, but theyaremuch more powerful. Let’sseewhy 
you might need such power. 



Programming in the Large 

When you first begin to design object-oriented programs, the class hierarchy seems almost 
miraculous. Within that single tree you can express a hierarchy of numeric types (number, 
complex, float, rational, integer), many simple-to-moderately-complex relationships between 
objectsand processesintheworld, and anynumberofpointsalongtheaxisfrom abstract/general 
to concrete/specific. After some deeper thought or more complex design experience, this 
wonderful tree begins to feel restrictive- at times, like a straitjacket. The very power and 
disci plineyou’veachieved by carefully placing only onecopy of each idea somewhereinthetree 
can come back to haunt you whenever you need to cross-fertilize disparate parts of that tree. 

Some languages address these problems by introducing more flexible run-time power, such as 
the code block and the perform : method of Smalltalk; others choose to provide more complex 
inheritance hierarchies, such as multiple-inheritance. W ith the latter complexity comes a host 
of confusing and error-proneambiguitiesand misunderstandings, and with theformer, a harder 
time implementing safety and security and a harder language to explain and teach. Java has 
chosen to take neither of these paths but, in the spirit of objective-C 's protocols, has adopted 
a separate hierarchy altogether to gain the expressive power needed to loosen the straitjacket. 

T his new hierarchy is a hierarchy of interfaces. I nterfaces are not limited to a single superclass, 
so they allow aform of multiple-inheritance. But they passon only method descriptionsto their 
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children, not method implementations nor instance variables, which helps to eliminate many 
of the complexities of full multiple-inheritance. 

Interfaces, likeclasses, aredeclared in source files, one interface to a file. Likedasses, they also 
are compiled into .class files. In fact, almost everywhere that this book has a class name in any 
of itsexamplesor discussions, you can substitute an i nterface name. J ava programmers often say 
"class" when they actually mean “class or interface.” Interfaces complement and extend the 
power of classes, and thetwocan be treated almost exactly the same. 0 neof thefew differences 
between them isthatan interfacecannot beinstantiated: new can createonlyan instanceof adass. 
H ere’s the declaration of an interface: 

package myFirstPackage; 

public interface MyFirstlnterface extends Interfacel , Interface2, ... { 

// all methods in here will be public and abstract 
// all variables will be public, static, and final 

> 

This example is a rewritten version of the first example in today’s lesson. It now adds a new 
public interface to the package myFirstPackage, instead of a new public class. Note that 
multiple parents can be listed in an interface's extends clause. 



Note: If no extends clause is given, interfaces do not default to inheriting from 
object, because object isadass. In fact, interfaces have no "topmost" interface 
from which they are all guaranteed to descend. 



Any variables or methods defined in a public interface are implicitly prefixed by the modifiers 
listed in the comments. Exactly those modifiers can (optionally) appear, but no others: 

public interface MySecondlnterface { 

public static final int theAnswer = 42; // both lines OK 

public abstract int lifeTheUniverseAndEverything() ; 

long bingBangCounter = 0; // OK, becomes public, static, final 

long ageOfTheUniversej) ; // OK, becomes public and abstract 

protected int aConstant; // not OK 

private int getAnlntj); // not OK 
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Note: If an interface is declared non-pubiic (that is, package), no public modifiers 
are implicitly prefixed. If you say public inside such an interface, you’re making a 
real statement of pubiic-ness, not simply a redundant statement. It's not often, 



■ though, that an interface is shared only by the classes inside a package, and not by 
the classes using that package as well. 



Design Versus I mplementation Revisited 

One of the most powerful things interfaces add to Java is the capability of separating design 
inheritance from implementation inheritance. In the single-class inheritance tree, these two are 
inextricably bound. Sometimes, you want to be able to describe an interface to a cl ass of objects 
abstractly, without having to implement a particular implementation of it yourself. You could 
create an abstract class, such as those described yesterday. In order for a new class to use this 
type of "interface,” however, it has to become a subclass of the abstract class and accept its 
position in thetree. If thisnew class also needsto beasubdassof some other class in the tree, 
for implementation reasons, what could it do? W hat if it wantsto use two such "interfaces” at 
once? Watch this: 

class Firstlmplementor extends SomeClass implements MySecondlnterface { 

> 

class Secondlmplementor implements MyFirstlnterface, MySecondlnterface { 

> 

Thefirst class above is "stuck" in thesingle inheritance treejust below the class someciass but 
isfreeto implement an interface as well. The second class is stuck just below object but has 
implemented two interfaces (it could have implemented any number of them). I implementing 
an interface means promising to implement all the methods specified in it. 



Note: Although an abstract class is allowed to ignore this strict requirement, and 
can implement any subset of the methods (or even none of them), all its non- 
abstract subclasses must still obey it. 



Because interfaces are in a separate hierarchy, they can be"mixed-in” to theclassesin thesingle 
inheritance tree, allowingthedesignerto sprinklean interfaceanywhereit isneeded throughout 
thetree. Thesingle-inheritance class tree can thusbe viewed as containing only the implemen- 
tation hierarchy; the design hierarchy (full of abstract methods, mostly) is contained in the 
multiple-inheritance interface tree. T his is a powerful way of thinking about the organization 
of your program, and though it takesa littlegetting used to, it’sal so ahighly recommended one. 

Let’s examine one simple example of this separation- creating the new class orange. Suppose 
you already have a good implementation of the class Fruit, and an interface, Fruitiike, that 
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represents what Fruits are expected to be able to do. You want an orange to be a fruit, but you 
also want it to beaspherical object that can be tossed, rotated, and so on. H ere’show to express 
it all: 

interface Fruitlike extends Foodlike { 
void decay(); 
void squish(); 

> 



class Fruit extends Food implements Fruitlike { 
private Color myColor; 
private int daysTillRot; 



interface Spherelike { 
void toss(); 
void rotate(); 

} 



class Orange extends Fruit implements Spherelike { 

... // toss()ing may squish() me (unique to me) 

> 

You’ll use this example again later today. For now, notice that dassorange doesn't have to say 
implements Fruituke because, by extending Fruit, it already has! 



Note: The reverse is not true, however. Implementing an interface implies nothing 
about the implementation hierarchy of a class. By the way, if you had used a more 
traditional way of designing classes (though not necessarily better), the class Fruit 
would be the interface description, as well as being the implementation. 



One of the nice things about this structure is that you can change your mind about what class 
orange extends (if a really great sphere class is suddenly implemented, for example), yet class 
orange will still understand the same two interfaces: 

class Sphere implements Spherelike { // extends Object 

private float radius; 



class Orange extends Sphere implements Fruitlike { 

... // users of Orange never need know about the change! 
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T he canonical use of the "mix-in" capability of interfaces is to allow several classes, scattered 
across the single-inheritance tree, to implement the same set of methods (or even just one). 



Although these classes share a common superclass (at worst, object), it is likely that below this 
common parent are many subclasses that are not interested in this set of methods. Adding the 
methods to the parent class, or even creating a new abstract class to hold them and inserting 
it into the hierarchy above the parent, is not an ideal solution. 

Instead, use an interface to specify the method (s). Itcan beimplemented by every class that 
shares the need and by none of the other classes that would have been forced to "understand” 
them in thesingle-inheritancetree. (D esign isapplied only whereneeded.) U sersof theinterf ace 
can now specify variables and arguments to be of anew interface type that can refer to any of 
the classes that implement the interface (as you’ll see below)— a powerful abstraction. Some 
examples of "mix-in” facilities are object persistence (via reado and write o methods), 
producing or consuming something (the Java library does this for images), and providing 
generally useful constants. T he last of these might look like this: 

public interface PresumablyUsefulConstants { 

public static final int oneOfThem = 1234; 

public static final float another = 1.234F; 

public static final String yetAnother = "1234"; 



public class AnyClass implements PresumablyUsefulConstants { 
public static void main (String argV [ ] ) { 

double calculation = oneOfThem * another; 

System. out. println( "hello " + yetAnother + calculation); 



Thisoutputsthethoroughlymeaninglessheiio 12341522.756, but in the process demonstrates 
that the class Anyciass can refer directly to all the variables defined in the interface 
PresumablyUsefulConstants. N ormally, you refer to such variables and constants via the class, 
as for the constant integer. min_value, which is provided by the integer class. If a set of 
constants is large or is widely used, the shortcut of being able to refer to them directly (as 
oneOfThem rather than aspresumabiyusefuiconstants. oneOfThem) makesitworth placing them 
into an interface and implementing it widely. 

Programming in the Small 

H owdoyou actually use these interfaces? Remember that almost everywhere that you can use 
adass, you can use an interface instead. Let’stryto makeuseof theinterfaceMysecondinterface 
defined previously: 

MySecondlnterface anObject = getTheRightObjectSomehow() ; 
long age = anObject.ageOfTheUniverse() ; 
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0 nceyou declareanobj ect to beof typewiysecondinterf ace, you can usGanobj ect asthereceiver 
of any messagethat theinterfacedefines(or inherits). What doesthepreviousdedaration really 
mean? 

Whenavariableisdeclaredto beof an interfacetype, it simply meansthat any object thevari able 
refers to is expected to have implemented that interface- that is, it is expected to understand 
all themethodsthat interfacespecifies. It assumes that a promise made between thedesigner of 
the interface and its eventual implementors has been kept. Although this is a rather abstract 
notion, it allows, for example, thepreviouscodeto bewritten long beforeanydassesthat qualify 
are actually implemented (or even created!). In traditional object-oriented programming, you 
are forced to create a class with "stub" implementations to get the same effect. 

H ere's a more complicated example: 

Orange anOrange = getAnOrangef) ; 

Fruit aFruit = (Fruit) getAnOrange( ) ; 

Fruitlike aFruitlike = (Fruitlike) getAnOrange( ) ; 

Spherelike aSpherelike = (Spherelike) getAnOrange( ) ; 



aFruit .decay () ; // fruits decay 

aFruitlike. squish() ; // and squish 



aFruitlike. toss( ) ; // not OK 

aSpherelike. toss() ; // OK 



anOrange. decay() ; // oranges can do it all 

anOrange. squish ( ) ; 
anOrange. toss () ; 
anOrange. rotate ( ) ; 

Declarationsand casts areused inthisexampleto restrict an orange to act morelikeamerefruit 
or sphere, simply to demonstrate the flexibility of the structure built previously. If the second 
structure built (the one with the new sphere class) were being used instead, most of thiscode 
would still work. (I n the line bearing Fruit, all instancesof Fruit need to bereplaced by sphere. 
The later use of aFruit. decay () COUld be replaced by, for example, aSphere.rotate(). 
Everything else is the same.) 



Note: The direct use of (implementation) class names is for demonstration pur- 
poses only. N ormally, you would use only interface names in those declarations 
and casts so that none of the code in the example would have to change to support 
the new structure. 
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I nterfaces are implemented and used throughout thej ava class library, whenever a behavior is 
expected to be implemented by a number of disparate classes. I n Appendix B you’ll find, for 
example, the interfaces java. lang. Runnable, java. util. Enumeration, java. util. Observable, 
j ava. awt. image. imageConsumer, and j ava. awt. image. imageProducer. Let's USe One Of these 
interfaces, Enumeration, to revisit the LinkedList example— and to ti etogether today's I esson — 
by demonstrating a good use of packages and interfaces together: 

package collections; 

public class LinkedList { 
private Node root; 



public Enumeration enumerate() { 

return new LinkedListEnumerator(root) ; 

} 



class Node { 

private Object contents; 
private Node next; 



public Object contents() { 
return contents; 



public Node next() { 
return next; 



class LinkedListEnumerator implements Enumeration { 
private Node currentNode; 

LinkedListEnumerator(Node root) { 
currentNode = root; 



public boolean hasMoreElements( ) { 
return currentNode != null; 



public Object nextElement( ) { 

Object anObject = currentNode. contents() ; 



currentNode = currentNode. next () ; 
return anObject; 
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H ere is a typical use of the enumerator: 

collections. LinkedList aLinkedList = createLinkedList() ; 
java. util. Enumeration e = aLinkedList. enumerate() ; 

while (e.hasMoreElements()) { 

Object anObject = e . nextElement ( ) ; 

// do something useful with anObject 

> 

N otice that although you areusingtheEnumeration e asthough you know what it is, you actually 
do not. In fact, it is an instance of a hidden class (LinkedListEnumerator) that you cannot see 
or usedirectly. By a combination of packages and interfaces, theLinkedList class has managed 
to provideatransparent public interface to someof its most important behavior (viatheal ready 
defined interface j ava. utii. Enumeration) whilestill encapsulating (hiding) its two implemen- 
tation (support) classes. 

H anding out an object like this is sometime called vending. Often, the "vendor” gives out an 
object that a receiver can’t create itself, but that it knows how to use. By giving it back to the 
vendor, the receiver can prove it has a certain capability, authenticate itself, or do any number 
of useful tasks— all without knowing much about the vended object. This is a powerful 
metaphor that can be applied in a broad range of situations. 

Summary 

T oday, you learned how packages can be used to collect and categorize classes into meaningful 
groups. Packages are arranged in a hierarchy, which not only better organizes your programs, 
but allows you and the millions of J ava programmers out on the N et to name and share their 
projects uniquely with one another. 

You also learned how to use packages, both your own and themany preexisting onesin thej ava 
class library. 

You then discovered how to declare and use interfaces, a powerful mechanism for extending the 
traditional single-inheritanceof J ava'sclassesand for separating thedesign inheritancefromthe 
implementation inheritance in your programs. I nterfaces are often used to call shared methods 
when the exact dassinvolved isnot known. You’ll see further uses of interfaces tomorrow and 
the day after. 

Finally, packages and interfaces can be combined to provide useful abstractions, such as 
Enumeration, that appear simpleyet are actually hiding almost all their (complex) implementa- 
tion from their users. T his is a powerful technique. 
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Q&A 

Q What will happen to packag^directory hierarchies when some sort of archiving 
is added to Java? 

A Being able to download over the N et a whole archive of packages, classes, and re- 
sources is something that Java systems may soon be able to do. When this happens, 
the simple mapping between directory hierarchy and package hierarchy will break 
down, and you will not be able to tell as easily where each class is stored (that is, in 
which archive). Presumably these new, advanced Java systems will provide tools that 
makethistask (and compiling and linking your program in general) much easier. 

Q Can you say import some. packaged* to import all the classes in that package that 
begin with b? 

A N o, the import asterisk (*) does not act like a command-line asterisk. 

Q Then what exactly does import-ing with an * mean? 

A Combining everything said previously, this precise definition emerges: it imports all 
the public classes that are directly inside the package named, and not inside one of its 
subpackages. (You can only import exactly this set of classes, or exactly one explicitly 
named class, from a given package.) By the way, J ava only "loads” the information for 
a class when you actually refer to that class in your code, so the * form of import is no 
less efficient than naming each class individually. 

Q I s there any way that a hidden (package) class can somehow be forced out of 
hiding? 

A A bizarre case in which a hidden class can be forced into visibility occurs if it has a 
public superclass and someone casts an instance of it to the superclass. Any public 
methods of that superclass can now be called via your hidden class instance, even if 
those methods were not thought of by you as public when overridden in the hidden 
class. Usually, these public methods are ones you don’t mind having your instances 
perform, or you wouldn't have declared them to have that public superclass. This isn’t 
always the case. M any of the system’s built-in classes are public— you may have no 
choice. Luckily, this is a rare event. 

Q Why is full multiple-inheritance so complex that Java abandoned it? 

A I t’s not so much that it is too complex, but that it makes the language overly compli- 
cated— and as you’ll learn on the final day, this can cause larger systems to be less 
trustworthy and thus less secure. For example, if you were to inherit from two 
different parents, each having an instance variable with the same name, you would be 
forced to allow the conflict and explain how the exact same references to that variable 
name in each of your superclasses, and in you (all three), are now different. I nstead of 
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being able to call "super” methods to get more abstract behavior accomplished, you 
would always need to worry about which of the (possibly many) identical methods 
you actually wished to call in which parent. Java’s run-time method dispatching would 
have to be more complex as well. Finally, because so many peoplewould be providing 
classes for reuse on the N et, the normally manageable conflicts that would arise in 
your own program would be confounded by millions of users mixing and matching 
these fully multi-inherited classes at will. In the future, if all these issues are resolved, 
more powerful inheritance may be added to J ava, but its current capabilities are 
already sufficient for 99 percent of your programs. 

Q abstract classes don't have to implement all the methods in an interface them- 
selves, but do all their subclasses have to? 

A Actually, no. Because of inheritance, the precise rule isthat an implementation must 
be provided by some class for each method, but it doesn't have to be your class. This is 
analogous to when you are the subclass of a class that implements an interface for you. 
Whatever the abstract class doesn't implement, the first nonabstract class below it 
must implement. Then, any further subclasses need do nothing further. 

Q You didn't mention callbacks. Aren't they an important use of interfaces? 

A Yes, but I didn’t mention them because a good example would be too bulky in the 
text. These callbacks are often used in user interfaces (such as window systems) to 
specify what set of methods are going to be sent whenever the user does a certain set of 
things (such as clicking the mouse somewhere, typing, and so forth). Because the user 
interface classes should not "know” anything about the classes using them, an 
interface’s ability to specify a set of methods separate from the class tree is crucial in 
this case. Callbacks using interfaces are not as general as using, for example, the 
perform: method of Smalltalk, however, because a given object can request that a user 
interface object "call it back" only by using a single method name. Suppose that object 
wanted two user interfaces objects of the same class to call it back, using different 
names to tell them apart? It cannot do this in Java, and it is forced to use special state 
and tests to tell them apart. (I warned you that it was complicated!). So, although 
interfaces are quite valuable in thiscase, they are not theideal callback facility. 
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T oday, you’ll learn about exceptional conditions in Java: 

□ H ow to declare when you are expecting one 

□ H ow to handle them in your code 

□ H ow to create them 

Z H ow your code is limited, yet made more robust by them 
Let's begin by motivating why new ways of handling exceptions were invented. 
Programming languages have long labored to solve the following common problem: 

int status = callSomethingThatAlmostAlwaysWorks( ) ; 

if (Status == FUNNY_RETURN_VALUE) { 

... // something unusual happened, handle it 

switch (someGlobalErrorlndicator) { 

... // handle more specific problems 

} 



Somehow this seems I ike a lot of work to do to hand lea rare case. W hat’sworse, if thefunction 
called returns an mt as part of its normal answer, you must distinguish one special integer 
(funny_return_value) to indicate an error. What if that function really needs all the integers? 
You must do something even more ugly. 

Even if you managetofind adistinguished value (such asNULL in C for pointers, -i for integers, 
and so forth), what if there are multiple errors that must be produced by the same function? 
Often, some global variable is used as an error indicator. Thefunction stores a value in it and 
prays that no one else changes it before the caller gets to handle the error. M ultiple errors 
propagate badly, if at all, and there are numerous problems with generalizing this to large 
programs, complex errors, and so forth. 

Luckily, there is an alternative: using exceptions to help you handle exceptional conditions in 
your program, making the normal, nonexceptional code cleaner and easier to read. 

NEW«* An exception is any object that is an instance of the class Throwabie (or any of 
TERM its subclasses). 

Programming in the Large 

When you begin to build complex programsin Java, you discover that after designing thedasses 
and interfaces, and their methodsdescriptions, you still havenot defined all thebehavior of your 
objects. After all, an interfacedescribesthenormal way to use an object and doesn't indudeany 
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strange, exceptional cases. In many systems, the documentation takes care of this problem by 
explicitly listing thedistinguished valuesused in "hacks" likethepreviousexample. Becausethe 
system knows nothing about these hacks, it cannot check them for consistency. In fact, the 
compiler can do nothing at all to help you with these exceptional conditions, in contrast to the 
helpful warnings and errors it produces if a method is used incorrectly. 

M oreimportantly, you havenot captured in your design thisimportant aspect of your program. 

I nstead, you areforced to makeup away to describeit in thedocumentation and hopeyou have 
not made any mistakes when you implement it later. What’s worse, everyone else makes up a 
different way of describing thesamething. Clearly, you need someuniform way of declaring the 
intentionsof classes and methodswith respectto these exceptional conditions.] ava provides just 
such away: 

public class MyFirstExceptionalClass { 

public void anExceptionalMethod() throws MyFirstException { 

} 

> 

H ere, you warn the reader (and the compiler) that the code. . . maythrow an exception called 

MyFirstException. 

You can think of a method’s description as a contract between the designer of that method (or 
class) and you, the caller of the method. Usually, this description tel Is the types of a method’s 
arguments, what it returns, and the general semantics of what it normally does. You are now 
being told, as well, what abnormal things it can do. This is a promise, just like the method 
promises to return a value of a certain type, and you can count on it when writing your code. 
These new promises help to tease apart and make explicit all the places where exceptional 
conditions should be handled in your program, and that makes large-scale design easier. 

Because exceptions are instances of classes, they can be put into a hierarchy that can naturally 
descri be therelationshipsamong thedifferent typesof exceptions. In fact, ifyou takeamoment 
to glance i n Appendix B at the diagramsfor j ava . iang-errors and j ava . iang-exceptions, you’ll 
see that thedass-mrowabie actually has two large hierarchies of classes beneath it.Therootsof 
these two hierarchies are subclasses of Throwabie called Exception and Error. These hierarchies 
embody therich set of relationshipsthat exist between exceptionsand errors inthej ava run-time 
environment. 

W hen you know that a particular kind of error or exception can occur in your method, you are 
supposed to either handleit yourself or explicitly warn potential callers about the possibility via 
the throws clause. Not all errors and exceptions must be listed; instancesofeitherdassErroror 
RuntimeException (orany of their subclasses) do not haveto belisted in yourthrows clause. T hey 
get special treatment because they can occur anywhere within ajava program and are usually 
conditions that you, as the programmer, did not directly cause. One good example is the 
outotMemoryError, which can happen anywhere, at any time, and for any number of reasons. 
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Note:You can, of course, choose to list these errors and run-time exceptions if you 
like, and the callers of your methods will be forced to handle them, just like a non- 
run-time exception. 

Whenever you see the word "exception" by itself, it almost always means "excep- 
tion or error" (that is, an instance of Thnowabie). T he previous discussion makes it 
clear that Exceptions and Errors actually form two separate hierarchies, but except 
for the throws clause rule, they act exactly the same. 



I f you examinethediagramsin Appendix B more carefully, you’ll noticethat there areonly five 
types of exceptions (in java.iang) that must be listed in a throws clause (remember that all 
Errors and RuntimeExceptions are exempt): 

□ ClassNotFoundException 

HlegalAccessException 

d InstantiationException 
d InterrupedException 

□ NoSuchMethodException 

E ach of these names suggests somethi ng that i s expl icitly caused by the programmer, not some 
behind-the-scenes event such asoutofMemoryError. 

I f you look further in Appendix B , near the bottom of thediagramsfor j ava . utu and j ava . io, 
you’ll see that each package adds some new exceptions. The former is adding two exceptions 
somewhat akin to ArraystoreException and indexoutofBoundsException, and so decides to 
place them under RuntimeException. T he latter is adding a whole new tree of ioExceptions, 
which are more explicitly caused by the programmer, and so they are rooted under Exception. 
Thus, ioExceptions must be described in throws clauses. Finally, packagejava.awt defines one 
of each style, implicit and explicit. 

TheJavaclasslibraryusesexceptionseverywhere,andto good effect. If you examinethedetailed 
API documentation in your Java release, you see that many of the methods in the library have 
throws clauses, and some of them even document (when they believe it will make something 
clearer to the reader) when they may throw one of the implicit errors or exceptions. T his isjust 
anicetyon the documentor’s part, because you are not required to catch conditionslikethat. 
If it wasn't obvious that such a condition could happen there, and for some reason you really 
cared about catching it, this would be useful information. 
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Programming in the Small 

N ow that you haveafeelingforhow exceptionscan hdpyou design a program and adasslibrary 
better, how do you actually use exceptions? Let’s try to use anExceptionaiMethodo defined in 
today’s first example: 

public void anotherExceptionalMethod() throws MyFirstException { 
MyFirstExceptionalClass aMFEC = new MyFirstExceptionalClass() 5 

aMFEC . anExceptionalMethod ( ) ; 

> 

Let’sexaminethisexamplemore closely. Ifyou assume that MyFirstException isasubdassof 
Exception, it meansthat ifyou don’t handleit in anotherExceptionaiMethod( ) 'scode, you must 
warnyourcallersaboutit.BecauseyourcodesimplycallsanExceptionaiMethodo withoutdoing 
anything about the fact that it may throw MyFirstException, you must add that exception to 
yourthrows clause. T hisisperfectly legal, but it doesdeFertoyourcaller something that perhaps 
you should be responsible for doing yourself. (It depends on the circumstances, of course.) 

Suppose that that you feel responsibletoday and decideto handletheexception. Becauseyou're 
now declaring a method without a throws clause, you must "catch” the expected exception and 
do something useful with it: 

public void responsibleMethod( ) { 

MyFirstExceptionalClass aMFEC = new MyFirstExceptionalClass () ; 



try { 

aMFEC. anExceptionaiMethodo ; 

} catch (MyFirstException m) { 

... //do something terribly significant and 



} 
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The try statement says basically: "Try running the code inside these braces, and if there are 
exceptionsthrown, I will attach handlers to take care of them.” (You first heard about these on 
Day 10.) You can have as many catch clauses at the end of atry as you need. Each allows you 
to handle any and all exceptions that are instances: of the class listed in parentheses, of any of 
its subclasses, or of adassthat implementstheinterfacelisted in parentheses. I n thecatch in this 
example, exceptions of the class MyFirstException (or any of its subclasses) are being handled. 



What if you want to combine both the approaches shown so far? You’d like to handle the 
exception yourself, butalso reflect it uptoyourcaller. Thiscan bedone, byexplicitly rethrowing 
the exception: 



public void responsibleExceptionalMethod() throws MyFirstException { 
MyFirstExceptionalClass aMFEC = new MyFirstExceptionalClass () ; 



try { 

aMFEC. anExceptionaiMethodo ; 
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} catch (MyFirstException m) { 

... //do something responsible 

throw m; // re-throw the exception 



This works because exception handlers can be nested. You handle the exception by doing 
something responsible with it, but decide that it is too important to not give an exception 
handler that might be in your caller a chance to handle it as well. Exceptions float all the way 
upthechain of method callersthisway (usually not being handled by most of them) until at last, 
the system itself handles any uncaught ones by aborting your program and printing an error 
message. In a stand-alone program, this is not such a bad idea; but in an applet, it can cause the 
browser to crash. M ost browsers protect themselvesfromthisdisaster by catching all exceptions 
themselves whenever they run an applet, but you can never tell. If it’s possible for you to catch 
an exception and do something intelligent with it, you should. 

Let'sseewhatthrowinganew exception lookslike. H ow about fleshing outtoday’sfirst example: 

public class MyFirstExceptionalClass { 

public void anExceptionalMethod() throws MyFirstException { 

if (someThingUnusualHasHappened() ) { 
throw new MyFirstException( ) ; 

// execution never reaches here 



> 




Note: throw isa little like a break statement— nothing "beyond it” is executed. 



This is the fundamental way that all exceptions are generated; someone, somewhere, had to 
create an exception object and throw it. In fact, the whole hierarchy under the classihrowabie 
would beworth much less if there were not throw statements scattered throughout the code in 
thejava library at just the right places. Because exceptions propagate up from any depth down 
inside methods, any method call you make might generate a plethora of possible errors and 
exceptions. Luckily, only the ones listed in the throws clause of that method need bethought 
about; the rest travel silently past on their way to becoming an error message (or being caught 
and handled higher in the system). 

H ere’san unusual demonstration of this, where the throw, and the handler that catches it, are 
very close together: 

System. out. print/ "Now "); 
try { 

System. out. print ("is "); 
throw new MyFirstException() ; 
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System.out.printC'a "); 

> catch (MyFirstException m) { 

System. out. print("the "); 

> 

System. out .print ( "time. “) ; 

It prints out Now is the time. 



Exceptions are really a quite powerful way of partitioning the space of all possible error 
conditions into manageable pieces. Because thefirst catch dausethatmatchesisexecuted,you 
can build chains such as the following: 



try { 

someReallyExceptionalMethod() ; 

> catch (NullPointerException n) { 

} catch (RuntimeException r) { 

> catch (IOException i) { 

} catch (MyFirstException m) { 

> catch (Exception e) { 



i subclass of RuntimeException 
i subclass of Exception 
i subclass of Exception 
>ur subclass of Exception 
i subclass of Throwable 

i caught here 



By listing subclasses before their parent classes, the parent catches anything it would normally 
catch that’salso not one of the subclasses above it. Byjugglingchainslikethese, you can express 
almost any combination of tests. If there’s some really obscure case you can’t handle, perhaps 
you can use an interface to catch it instead. T hat allowsyou to design your (peculiar) exceptions 
hierarchy using multiple inheritance. Catching an interface rather than a class can also be used 
to test for a property that many exceptions share but that cannot be expressed in the single- 
inheritance tree alone. 



Suppose, for example, that a scattered set of your exception classes require a reboot after being 
thrown. You createan interfacecalled NeedsReboot, and all thesedassesimplementtheinterface. 
(N one of them needs to have a common parent exception class.) T hen, the highest levd of 
exception handler simply catches classes that implement NeedsReboot and performs a reboot: 

public interface NeedsReboot { } // needs no contents at all 



try { 

someMethodThatGeneratesExceptionsThatlmplementNeedsReboot ( ) ; 

> catch (NeedsReboot n) { // catch an interface 

... // cleanup 

SystemClass. reboot () ; // reboot using a made-up system class 

> 

Bytheway, if you need really unusual behavior during an exception, you can placethe behavior 
into theexception dassitsdf! Rememberthat an exception isalso anormal class, so it can contain 
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in stance variables and methods. Although usingthem isalittlepeculiar, itmightbevaluableon 
a few bizarre occasions. H ere’swhat this might look like: 

try { 

someExceptionallyStrangeMethod ( ) ; 

> catch (ComplexException e) { 

switch (e.internalState() ) { // probably an instance variable value 

case e . COMPLEX_CASE : // a class variable of the exception 

e.performComplexBehavior(myState, theContext, etc); 
break; 



> 

> 

T he L imitations P laced 
on the Programmer 

As powerful as all this sounds, isn’t it a little limiting, too? For example, suppose you want to 
override one of the standard methods of theob j ect class, tostring ( > , to be smarter about how 
you print yourself: 

public class MylllegalClass { 
public String toString() { 

someReallyExceptionalMethod ( ) ; 

... // returns some String 

> 

> 

Becausethesuperclassfobj ect) defined themethod declaration fortostringo without a throws 
clause, any implementation of it in any subclass must obey this restriction. In particular, you 
cannot just call someReallyExceptionalMethod o,asyou did previously, becauseit will generate 
a host of errors and exceptions, someof which arenot exempt from being listed in athrows clause 
(such as ioException and MyFirstException). If all the exceptions thrown were exempt, you 
would haveno problem, but becausesomearenot, you haveto catch at least thosefew exceptions 
for this to be legal Java: 

public class MyLegalClass { 
public String toString() { 
try { 

someReallyExceptionalMethod () ; 

} catch (lOException e) { 

} catch (MyFirstException m) { 
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I n both cases, you elect to catch theexceptionsand do absolutely nothing with them. Although 
this is legal, it isnot always theright thing to do. You may need to think for a whileto come up 
with the best, nontrivial behavior for any particular catch clause. T his extra thought and care 




makes your program more robust, better ableto handle unusual input, and more likely to work 
correctly when used by multiple threads (you’ll see this tomorrow). 

Myiiiegaiciass’s tostring( ) method produces a compiler error to remind you to reflect on 
these issues. This extra care will richly reward you as you reuse your cl asses in later projects and 
in larger and larger programs. 0 f course, thejava class library has been written with exactly this 
degreeof care, and that’soneofthereasonsit’srobust enough to beused in constructingall your 
J ava projects. 

The finally Clause 

Finally, for finally. Suppose thereissomeaction that you absolutely must do, no matter what 
happens. U sually, this is to free some external resource after acquiring it, to close a file after 
opening it, or so forth. T o be sure that "no matter what” includes exceptions as well, you use 
a clause of the try statement designed for exactly this sort of thing, t many: 

SomeFileClass f = new SomeFileClass( ) ; 

if (f .open( “ /a/file/name/path" ) ) { 
try { 

someReallyExceptionalMethod() ; 

} finally { 
f .close() ; 



This use of finally behaves very much like the following: 

SomeFileClass f = new SomeFileClass ( ) ; 

if (f .open("/a/file/name/path")) { 
try { 

someReallyExceptionalMethod( ) ; 

} catch (Throwable t) { 
f .close() ; 
throw t; 

} 

} 

except that finally can also beused to clean up not only after exceptionsbut after return, break, 
and continue statements as well. H ere’s a complex demonstration: 

public class MyFinalExceptionalClass extends ContextClass { 
public static void main(String argv[]) { 
int mysteriousState = getContext() ; 

while (true) { 

System. out. print ("Who "); 
try { 

System. out. print ("is "); 
if (mysteriousState == 1) 
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return; 

System. out. print("that "); 
if (mysteriousState == 2) 
break; 

System. out. print ("strange "); 
if (mysteriousState == 3) 
continue; 

System. out. print ( "but kindly "); 
if (mysteriousState == 4) 

throw new UncaughtException() ; 

System, out. print ("not at all "); 

> finally { 

System. out. print ( "amusing "); 

> 

System. out. print("yet compelling "); 

} 

System. out. print("man?") ; 

> 

> 

H ere is the output produced depending on the value of mysteriousState: 

1 Who is amusing 

2 Who is that amusing man? 

3 Who is that strange amusing Who is that strange amusing . . . 

4 Who is that strange but kindly amusing 

5 Who is that strange but kindly not at all amusing yet compelling man? 



Note: In case 3, the output never ends until you press Ctrl-fC. In 4, an error 
message generated by theuncaughtException is also printed. 



Summary 

T oday, you learned about how exceptions aid your program's design, robustness, and 
multithreading capability (more on this tomorrow). 

You also learned about the vast array of exceptions defined and thrown in thejava class library, 
andhowtotrymethodswhilecatch-inganyofahierarchicallyorderedsetofpossibleexceptions 
and errors. Java’s reliance on strict exception handling does place some restrictions on the 
programmer, but you learned that these restrictions are light compared to the rewards. 

Finally, the finally clause was discussed, which provides a fool-proof way to be certain that 
something is accomplished, no matter what. 
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Q&A 

Q I'd like to test the last example you gave, but where does getcontexto come 
from? 

A T hat example wasn’t meant to be an executable program as it stands, but you can turn 
it into one as follows. First, remove the clause extends contextciass from line one. 
Then, replace getcontexto in the third line with 

integer. parseint(args[0] ). You can now compile, then run, the example via the 
following: 

java MyFinalExceptionClass N 

where n is the mysterious state you want. 

Q I'm still not sure I understand the differences between Exceptions, Errors, and 
RuntimeExceptions . I s there another way of looking at them? 

A Errors are caused by dynamic linking, or virtual machine problems, and are thus too 
low-level for most programs to care about (although sophisticated development 
libraries and environments probably care a great deal about them). 
RuntimeExceptionsare generated by the normal execution of Java code, and though 
they occasionally reflect a condition you will want to handle explicitly, more often 
they reflect a coding mistake by the programmer and simply need to print an error to 
help flag that mistake. Exceptionsthat are not RuntimeExceptions (ioExceptions, for 
example) are conditions that, because of their nature, should be explicitly handled by 
any robust and well-thought-out code. Thejava class library has been written using 
only a few of these, but they are extremely important to using the system safely and 
correctly. T he compiler helps you handle these exceptions properly via its throws 
clause checks and restrictions. 

Q Is there any way to "get around" the strict restrictions placed on methods by the 
throws clause? 

A Yes. Suppose you thought long and hard and have decided that you need to circum- 
vent this restriction. This is almost never the case, because the right solution is to go 
back and redesign your methods to reflect the exceptions that you need to throw. 
Imagine, however, that for some reason a system class has you in a straitjacket. Your 
first solution is to subclass RuntimeException to makeup anew, exempt exception of 
your own. N ow you can throw it to your heart's content, because the throws clause 
that was annoying you does not need to include this new exception. If you need alot 
of such exceptions, an elegant approach isto mixin some novel exception interfaces to 
your new Runtime classes. You're free to choose whatever subset of these new interfaces 
you want to catch (none of the normal Runtime exceptions need be caught), while any 
leftover (new) Runtime exceptions are (legally) allowed to go through that otherwise 
annoying standard method in the library. 
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Q I'm still a little confused by long chains of catch clauses. Can you label the 
previous example with which exceptions are handled by each line of code? 

A Certainly, here it is: 

try { 

someReallyExceptionalMethodO ; 

> catch (NullPointerException n) { 

... // handles NullPointerExceptions 

} catch (RuntimeException r) { 

... // handles RuntimeExceptions that are not NullPointerExceptions 

> catch (IOException i) { 

... // handles IOExceptions 

} catch (MyFirstException m) { 

... // handles MyFirstExceptions 

> catch (Exception e) { // handles Exceptions that are not RuntimeExceptions 

... // nor IOExceptions nor MyFirstExceptions 

} catch (Throwable t) { 

... // handles Throwables that are not Exceptions (i.e., Errors) 

> 

Q G iven how annoying it can sometimes be to handle exceptional conditions 
properly, what's stopping me from surrounding any method with a throws clause 
as follows: 

try { thatAnnoyingMethod() ; } catch (Throwable t) { } 

and simply ignoring all exceptions? 

A Nothing, other than your own conscience. In some cases, you should do nothing, 
because it is the correct thing to do for your method’s implementation. Otherwise, 
you should struggle through the annoyance and gain experience. Good style is a 
struggle even for the best programmer, but the rewards are rich indeed. 
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T oday, you’ll learn more about the threads mentioned briefly in Week 2: 

□ H ow to "think multithreaded" 

□ H ow to protect your methods and variables from unintended thread conflicts 
Z H ow to create, start, and stop threads and threaded classes 

Z H ow the scheduler works in Java 
First, let’s begin by motivating the need for threads. 

Threads are a relatively recent invention in the computer science world. Although processes, 
their larger parent, have been around for decades, threadshaveonly recently been accepted into 
the mainstream. W hat’sodd about thisisthat they are very valuable, and programswritten with 
th em are n oti ceably better, even to th e casu al u ser . I n f act, som e of th e best i n d i vi d u al , H ercu I ean 
efforts over the years have involved implementing a threads-like facility by hand to give a 
program a more friendly feel to its users. 

I maginethat you’re using your favorite text editor on a large file. When it startsup, doesitneed 
to examine the entire file before it lets you edit? D oes it need to make a copy of thefile? If the 
fileishuge, thiscan beanightmare. Wouldn’t it benicer for ittoshow you thefirst page, enabling 
you to begin editing, and somehow (in thebackground) completetheslowertasksnecessaryfor 
initialization? Threads allow exactly this kind of within-the-program parallelism. 

Perhaps the best example of threading (or lack of it) is a WWW browser. Can your browser 
download an indefinite number of files and Web pages at once while still enabling you to 
continue browsing? W hile these pages are downloading, can your browser download all the 
pictures, sounds, and so forth in parallel, interleaving the fast and slow download times of 
multiple I nternet servers? H otj ava can do all of these things— and more— by using the built- 
in threading of thejava language. 

The Problem with Parallelism 

If threading isso wonderful, why doesn’t every system haveit?M any modern operating systems 
havethebasicprimitivesneededto createand run threads, but they aremissing a key ingredient. 
T he rest of their environment isnot thread-safe. I maginethat you are in a thread, oneof many, 
and each of you issharing some important data managed bythesystem. Ifyou weremanaging 
that data, you could takestepsto protect it (asyou’ll see later tod ay), butthesystem ismanaging 
it. N ow visualizea piece of codein thesystem that reads some crucial value, thinks about it for 
awhile, and then adds i to the value: 

if (crucialValue > 0) { 

... // think about what to do 

crucialValue += 1 ; 

} 
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Remember that any number of threads may be calling upon this part of the system at once. T he 
disaster occurswhen two threads have both executed theif test before either has incremented 
thecruciaivaiue. I n that case, thevalueisdobbered by them both with thesamecruciaivaiue 
+ i, and one of the increments has been lost. This may not seem so bad to you, but imagine 
instead that the crucial value affects the state of the screen as it is being displayed. N ow, 
unfortunate ordering of thethreadscan cause the screen to beupdated incorrectly. In the same 
way, mouse or keyboard eventscan belost, databases can be in accurately updated, and so forth. 

T hisdisaster isinescapableif any significant part ofthesystemhasnot been written with threads 
in mind. Therein lies the barrier to a mainstream threaded environment— the large effort 
required to rewrite existing librariesforthread safety. Luckily, J avawaswritten from scratch with 
this is mind, and every Java cl ass in its library isthread-safe. Thus, you now have to worry only 
about your own synchronization and thread-ordering problems, because you can assume that 
thej ava system will do the right thing. 

NEW** Atomic operations are operations that appear to happen "all at once”— exactly 

TERM at the same time- to other threads. 



Note: Some readers may wonder what the fundamental problem really is. Can’t 
you just make the... area in the example smaller and smaller to reduce or eliminate 
the problem? W ithout atomic operations, the answer is no. Even if the 
... took zero time, you must first look at the value of some variable to make any 
decision and then change something to reflect that decision. T hese two steps can 
never be made to happen at the same time without an atomic operation. Unless 
you’re given one by the system, it’s literally impossible to create your own. 

Even the one line cruciaivaiue += i involves three steps: get the current value, add 
one to it, and store it back. (U sing ++cruciaivaiue doesn’t help either.) All three 
steps need to happen "all at once” (atomically) to be safe. Special Java primitives, at 
the lowest levels of the language, provide you with the basic atomic operations you 
need to build safe, threaded programs. 



T hinking M ultithreaded 

Getting used to threads takes a little while and anew way of thinking. Rather than imagining 
that you always know exactly what's happening when you look at a method you’ve written, you 
have to ask yourself some additional questions. What will happen if more than onethread calls 
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into this method at the same time? Do you need to protect it in some way? What about your 
class as a whole? Are you assuming that only one of its methods is running at the same time? 

Often you make such assumptions, and a local instance variable will be messed up as a result. 
Let’s make a few mistakes and then try to correct them. First, the simplest case: 

public class ThreadCounter { 
int crucialValue; 

public void countMe() { 
crucialValue += 1 ; 

} 

public int howManyO { 
return crucialValue; 

} 

} 

Thiscodesuffersfromthemostpureform of the "synchronization problem:” the+= takes more 
than onestep, and you may miscountthenumber of threadsasa result. (D on’t worry about how 
threads are created yet, just imagine that a whole bunch of them are able to call countMeo, at 
once, at slightly different times.) Java allows you to fix this: 

public class SafeThreadCounter { 
int crucialValue; 

public synchronized void countMe() { 
crucialValue += 1 ; 

} 

public int howManyO { 

return crucialValue; 



Thesynchronized keyword tel I sj ava to maketheblock of codein themethod thread safe. 0 nly 
onethread will be allowed insidethismethod at once, and othershaveto wait until thecurrently 
running thread is finished with it before they can begin running it. This implies that 
synchronizing a large, long-running method isalmostalwaysabad idea. All your threadswould 
end up stuck at this bottleneck, waitingin singlefileto get their turn atthisoneslow method. 

I t’seven worse than you might think for most unsynchronized variables. Because thecompiler 
can keep them around in registers during computations, and a thread's registers can’t be seen 
by other threads (especially if they’re on another processor in a true multiprocessor computer), 
a variable can be updated in such a way that no possible order of thread updates could have 
produced the result. T his is completely incomprehensible to the programmer. T o avoid this 
bizarre case, you can label a variable volatile, meaning that you know it will be updated 
asynchronously by multiprocessor-like threads. Java then loads and stores it each time it’s 
needed and does not use registers. 
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Points About Points 



The method howManyo in the last example doesn't need to fc 
returnsthe current valueof an instance variable. Someonehj 
be synchronized, though— someone who uses the value^ 
example: 




public float y() { 
return y; 

} 

... // methods to set 



public class UnsafePointPi 
public void print(Pc 
System. out. pi ' i 



The analogous mj 
they just retui 
y ( > to decidi 
method p^ ' 
there is; 
could, 
ho\ 



hey need no synchronization, because 
PTs the responsibility of the caller of xo and 
PTtself— and in this case, it does. Although the 
ITlnts them out, it readstwo values. This means that 
IffTrunning between thecalltop.xo andthecalltop.yo, 
JT^d y stored insidethepomt p. Remember, you don’t know 
Ewayto reach and call methods in thispomt object! "Thinking 
Tito being careful anytimeyou makean assumption that something 
Wee n two parts of your program (even two parts of the same line, or the 
5Tch as the string + expression in this example). 





Multithreading 



TryAgainPointPrinter 

You could try to make a safe version of print o by simply adding the synchronized keyword 
modifier to it, but instead, let’s try a slightly different approach: 



public class TryAgainPointPrinter { 
public void print (Point p) { 
float safeX, safeY; 



synchronized(this) { 

safeX = p.x(); // these two lines now 

safeY = p - y ( ) ; // happen atomically 

} 

System. out. print ("The point's x is " + safeX 
+ " y is " + safeY) ; 



The synchronized statement takes an argument that sayswhat object you would liketo lock to 
prevent morethan onethread from executing theendosed block of codeatthesametime. H ere, 
you usethis (the instance itself), which isexactly theobject that would have been locked by the 
synchronized method as a whole if you had changed printo to be like your safe countMeo 
method. You have an added bonus with this new form of synchronization: you can specify 
exactly what part of a method needs to be safe, and the rest can be left unsafe. 



N otice how you took advantage of this freedom to make the protected part of the method as 
small as possible, while leaving the string creations, concatenations, and printing (which 
together take a small but nonzero amount of time) outside the "protected” area. This is both 
good style (as a guide to the reader of your code) and more efficient, because fewer threads get 
stuck waiting to get into protected areas. 



SafePointPrinter 

The astute reader, though, may still beworried by the last example. It seems as if you madesure 
that nooneexecutesyourcallstoxo and y o out of order, but have you prevented the point p 
from changing out from under you?Theanswerisno, you still havenot solved theproblem. You 
really do need the full power of the synchronized statement: 

public class SafePointPrinter { 
public void print (Point p) { 
float safeX, safeY; 

synchronized(p) { //no one can change p 
safeX = p.x(); // while these two lines 

safeY = p.y(); // are happening atomically 

} 

System. out. print("The point's x is 11 + safeX 
+ " y is " + safeY) ; 



358 



N ow you’ve got it. You actually needed to protect the point p to protect from changes, so you 
lock it by giving it as the argument to your synchronized statement. N ow when x<> and y() 
happen together, they can be sure to get the current x and y of the point p, without any other 
thread being ableto call a modifying method between. You 're still assuming, however, that the 
point p has properly protected itself. (You can alwaysassumethisabout system classes- but you 
wrote this point class.) You can make sure by writing the only method that can change x and 
y inside p yourself: 

public class Point { 
private float x, y; 

... // the x() and y() methods 

public synchronized void setXAndY(float newX, float newY) { 



By making the only "set" method in point synchronized, you guarantee that any other thread 
trying to grab the point P and change it out from under you hasto wait: you’ve locked thepomt 
p with your synchronized <p) statement, and any other thread hasto try to lock thesamepomt 
P via the implicit synchronized(this) statement P now executes when entering setxAndYQ. 
Thus, at last, you are thread-safe. 



Note: By the way, if Java had someway of returning more than one value at once, 
you could write a synchronized getxAndYo method for points that returns both 
values safely. In the current Java language, such a method could return a new, 
unique point to guarantee to its callers that no one else has a copy that might be 
changed. T his sort of trick can be used to minimize the parts of the system that 
need to worry about synchronization. 



ReallySafePoint 

An added benefit of theuseofthesynchronizedmodifieronmethods(or of synchronized (this) 
{. . .>) isthatonlyoneofthesemethods(orblocksof code) can run at once. You can use that 
knowledge to guarantee that only one of several crucial methods in a class will run at once: 

public class ReallySafePoint { 
private float x, y; 

public synchronized Point getUniquePoint ( ) { 

return new Point(x, y); // can be a less safe Point 

} // because only the caller has it 
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public synchronized void setXAndY (float newX, float newY) { 
y = newY; 



public synchronized void scale (float scaleX, float scaleY) { 
x *= scaleX; 
y *= scaleY; 

} 

public synchronized void add(ReallySafePoint aRSP) { 

Point p = aRSP.getUniquePoint() ; 

x += p.x(); 

y += p-y(); 

} // Point p is soon thrown away by GC; no one else ever saw it 

} 

Thisexamplecombines several of the ideas mentioned previously. To avoid a caller’s having to 
synchronize(p) whenever getting your x and y, you give them a synchronized way to get a 
uniquepomt (likereturning multiple values). Each method that modifies the object’s instance 
variables is also synchronized to prevent it from running between the x and y references in 
getuniquepomto and from stepping on the others as they each modify the local x and y . N ote 
that add () itself uses getuniquepomto to avoid having to Say synchronized (aRSP). 

C lassesthat arethissafearealittleunusual; it ismoreoften your responsibility to protect yourself 
from other threads’ use of commonly held objects (such as points). 0 nly when you know for 
certain that you’re the only one that knows about an object, can you fully relax. Of course, if 
you created the object and gave it to no one else, you can be that certain. 

Protecting a Class Variable 

Finally, supposeyouwantadassvariableto collect someinformationacrossalladass’sinstances: 

public class StaticCounter { 

private static int crucialValue; 

public synchronized void countMe() { 
crucialValue += 1 ; 

} 

> 

I sthis safe? If cruciaivaiue were an instance variable, itwould be. Because it’sa class variable, 
however, and there is only one copy of it for all instances, you can still have multiple threads 
modifying it by using different instances of the class. (Remember, the synchronized modifier 
locks theobject this— an instance.) Luckily, you already know thetoolsyou need to solvethis: 

public class StaticCounter { 

private static int crucialValue; 



360 



public void countMe() { 

synchronized(getClass()) { // can't directly reference StaticCounter 

crucialValue += 1 ; // the (shared) class is now locked 



> 

T hetrick isto "lock" on adifferent object— not on an instanceof thedass, but on thedassitself. 
Becauseadassvariableis"inside" adass, just as an instance variable is inside an instance, this 
shouldn’t be all that unexpected. In a si mi lar way, classes can provideglobal resources that any 
instance (or other class) can access directly by using thedass name, and lock by using that same 
dassname. I n thisexample, cruciaivaiue isused from within an instanceof StaticCounter, but 
if cruciaivaiue were declared public instead, from anywhere in the program, it would be safe 
to say the following: 

synchronized(new StaticCounter() .getClass()) { 

StaticCounter. cruciaivaiue += 1; 



Note: The direct use of another object’s variable is really bad style- it’s used here 
simply to demonstrate a point quickly. StaticCounter normally provides a 
countMeo-like class method of its own to do this sort of dirty work. 



You can appreciate how much work thejavateam hasdoneforyou by thinking all these hard 
thoughts for each and every class (and method!) in thejava class library. 



C reating and U sing T hreads 

N ow that you understand thepower (and thedangers) of having many threadsrunning at once, 
how are those threads actually created? 




Warning: The system itself always has a few so-called daemon threadsrunning, one 
of which is constantly doing the tedious task of garbage collection for you in the 
background. There is also amain user thread that listens for events from your 
mouse and keyboard. If you’re not careful, you can sometimes lock out this main 
thread. If you do, no events are sent to your program and it appears to be dead. A 
good ruleof thumb isthat whenever you’re doing something that can bedonein a 
separate thread, it probably should be. T hreads in J ava are relatively cheap to create, 
run, and destroy, so don’t use them too sparingly. 
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B ecausethereisaclassjava.iang. Thread, you might guessthat you could create a thread of your 
own by subclassing it- and you are right: 

public class MyFirstThread extends Thread { // a.k.a., java. lang. Thread 
public void run() { 

... //do something useful 

} 

> 

You now have a new type of Thread called MyFirstThread, which does something useful 
(unspecified) when itsruno method iscalled. 0 f course, no onehascreated thisthread or called 
its run o method, so it does absolutely nothing at the moment. To actually create and run an 
instance of your new thread class, you write the following: 

MyFirstThread aMFT = new MyFirstThread () ; 
aMFT. start () ; // calls our run() method 

What could be simpler? You create a new instance of your thread class and then ask it to start 
running. W henever you want to stop the thread, you use this: 

aMFT. stop () ; 

Besidesrespondingto start < > and stop( >, a thread can also betemporarily suspended and later 
resumed: 

Thread t = new Thread/); 
t. suspend/) ; 

... //do something special while t isn't running 

t. resume/); 

A thread will automatically suspend/) and then resume/ ) When it’sfirst blocked at a synchro- 
nized point and then later unblocked (when it’s that thread's "turn" to run). 



The Runnable Interface 



Thisisall well and good if every time you want to create aThread you have the luxury of being 
ableto placeit undertheThread classi n thesi ngle-inheritancecl ass tree. W hat if it morenatu rally 
belongs under some other class, from which it needs to get most of its implementation? The 
interfaces of D ay 16 come to the rescue: 



public class MySecondThread extends ImportantClass implements Runnable { 
public void run/) { 

... //do something useful 

} 
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By implementing theinterfaceRunnabie, you declare your intention to run in a separatethread. 
I n fact, the class Thread itself implements this interface, as you might expect from the design 
discussions on D ay 16. As you also might guess from the example, the interface Runnable 




specifiesonlyonemethod:run().AsinMyFirstThread, you expect someonetocreatean instance 
of a thread and somehow call your runo method. H ere’show this is accomplished: 

MySecondThread aMST = new MySecondThread() ; 

Thread aThread = new Thread(aMST) ; 

aThread. start () ; // calls our run() method, indirectly 

First, you createaninstanceof MySecondThread. Then, by passingthisinstancetotheconstructor 
maki ng the new Thread, you make it thetarget of that Thread. W henever that new Thread starts 
up, its run< ) method callstheruno method of thetarget it was given (assumed by the Thread 
to bean object that implements the Runnable interface). When starto is called, aThread 
(indirectly) callsyourruno method. You can stop aThread with stopo. If you don't need to talk 
to the Thread explicitly or to the instance of MySecondThread, here’s a one line shortcut: 

new Thread(new MySecondThread)) ) .start() ; 



N ote: As you can see, the class name, MySecondThread, is a bit of a misnomer- it 
does not descend from Thread, nor is it actually the thread that you starto and 
stopo. It probably should have been called MysecondThreadedciass or 

ImportantRunnableClass. 



ThreadTester 

H ere’s a longer example: 

public class SimpleRunnable implements Runnable { 
public void run() { 

System. out. println)" in thread named 1 " 

+ Thread. currentThread)) .getName)) + ); 

} // any other methods run() calls are in current thread as well 



public class ThreadTester { 

public static void main(String argv[]) { 

SimpleRunnable aSR = new SimpleRunnable)); 

while (true) { 

Thread t = new Thread(aSR); 



System. out. println("new Thread)) " + (t == null ? 

“fail" : "succeed") + "ed.“); 

t. start)) ; 

try { t.join)); > catch (InterruptedException ignored) { > 

// waits for thread to finish its run)) method 
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Note: You may be worried that only one instance of the class simpieRunnabie is 
created, but many new Threads are using it. D on’t they get confused? Remember to 
separate in your mind the asR instance (and the methods it understands) from the 
various threads of execution that can passthrough it. asR’s methods provide a 
template for execution, and the multiple threads created are sharing that template. 
Each remembers where it is executing and whatever else it needs to make it distinct 
from the other running threads. They all share the same instance and the same 
methods. That’s why you need to be so careful, when adding synchronization, to 
imagine numerous threads running rampant ova each of your methods. 



ThedassmethodcurrentThreado can becalled to getthethread in which amethod iscurrently 
executing. If the simpieRunnabie class were a subclass of Thread, its methods would know the 
answer already (it is the thread running). Because simpieRunnabie simply implements the 
interface Runnable, howeva, and counts on someone else(ThreadTester’smaino) to create the 
thread, itsrun ( > method needsanotha way to get itshandson that thread. 0 ften, you’ll bedeep 
insidemethodscalled byyourruno method when suddenlyyou need to getthecurrentthread. 
The class method shown in the example works, no matter whae you are. 



Warning: You can do some reasonably disastrous things with your knowledge of 
threads. For example, if you’re running in the main thread of the system and, 
because you think you are in adiffaent thread, you accidentally say the following: 

Thread. currentThread() .stop() ; 

it has unfortunate consequences for your (soon-to-be-dead) program! 

The example then calls on getNameo, the current thread to get the thread's name (usually 
something helpful, such asThread-23) so it can tell theworld in which thread runo isrunning. 
The final thing to note is the use of the method joint), which, when sent to athread, means 
"I 'm planning to wait foreva for you to finish your run ( ) method.” You don't want to do this 
lightly: if you have anything else important you need to get done in your thread any timesoon, 
you can’t count on how long the joint >ed thread maytaketo finish. In theexample, itsruno 
method isshort and finishesquickly, so each loop can safely wait for the previous thread to die 
before creating the next one. (Of course, in this example, you didn't have anything else you 
wanted todowhilewaiting for jomo anyway.) H ere's the output produced: 

new Thread () succeeded. 
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in thread named 'Thread-1' 
new Thread () succeeded, 
in thread named 'Thread -2' 
new Thread () succeeded, 
in thread named 'Thread -3' 
A C 



Ctrl-fC was pressed to interrupt the program, because it otherwise would continue forever. 



N a medT h rea dT ester 

I f you want your threadsto have particular names, you can assign them yourself by using a two- 
argument form of Thread’s constructor: 

public class NamedThreadTester { 

public static void main(String argv[]) { 

SimpleRunnable aSR = new SimpleRunnable() ; 

for (int i = 1; true; ++i) { 

Thread t = new Thread(aSR, " " + (100 - i) 

+ " threads on the wall..."); 

System. out. println("new Thread() " + (t == null ? 

"fail" : "succeed") + "ed.“); 

t. start () ; 

try { t.join(); > catch (InterruptedException ignored) { > 

} 

} 

> 

which takes a target object, as before, and a string, which names the new thread. H ere’sthe 
output: 

new Thread () succeeded. 

in thread named '99 threads on the wall...' 
new Thread () succeeded. 

in thread named '98 threads on the wall...' 
new Thread () succeeded. 

in thread named '97 threads on the wall...' 

A C 



N aming a thread is one easy way to pass it some i nformation. T his information flows from the 
parentthread to itsnew child. I t’salso useful, for debugging purposes, togivethreadsmeaningful 
names (such as network input) so that when they appear during an error- in a stack trace, for 
example— you can easily identify which thread caused the problem. You might also think of 
using names to help group or organize your threads, but Java actually provides you with a 
ThreadGroup class to perform this function. A ThreadGroup allows you to group threads, to 
control them all as a unit, and to keep them from being able to affect other threads (useful for 
security). 
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Knowing When a Thread has Stopped 

Let’s imagine a different version of the last example, one that creates a thread and then hands 
thethread off to other partsof theprogram. Supposeit would then liketo know when thatthread 
diesso that it can perform some cleanup operation. If simpieRunnabiewereasubdassof Thread, 
you might try to catch stopo whenever it'ssent — butlookatThread’sdeclaration ofthestopo 
method: 

public final void stop(); { . . . > 

The final here means that you can't override this method in a subclass. In any case, 
simpieRunnabie isnot asubdassof Thread, so how can thisimagined example possibly catch the 
death of its thread? The answer is to use the following magic: 

public class SingleThreadTester { 

public static void main(String argv[]) { 

Thread t = new Thread(new SimpleRunnable( ) ) ; 

try { 

t. start () ; 

someMethodThatMightStopTheThread ( t ) ; 

} catch (ThreadDeath aTD) { 

... //do some required cleanup 

throw aTD; // re -throw the error 

> 

> 

} 

You understand most of this magic from yesterday’s lesson. All you need to know isthat if the 
thread created intheexampledies, itthrowsan error of dassThreadDeath.Thecodecatchesthat 
error and performs the required cleanup. It then rethrows the error, allowing thethread to die. 
The cleanup code is not called if thethread exits normally (its run o method completes), but 
that’s fine; you posited that the cleanup was needed only when stopo was used on thethread. 



Note: Threads can die in other ways- for example, by throwing exceptions that no 
one catches. I n these cases, stopo is never called, and the previous code is not 
sufficient. (If the cleanup always has to occur, even at the normal end of a thread’s 
life, you can put it in a finally clause.) Because unexpected exceptions can come 
out of nowhere to kill a thread, multithreaded programs that carefully catch and 
handle all their exceptions are more predictable, robust, and easier to debug. 
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Thread Scheduling 

You might wonder exactly what order your threadswill be run in, and how you can control that 
order. U nfortunately, the current implementations of thej ava system cannot precisely answer 
the former, though with a lot of work, you can always do the latter. 

NEW*' T he part of the system that decides the real-time ordering of threads is called the 
TERM scheduler. 

Preemptive Versus Nonpreemptive 

N ormally, any scheduler has two fundamentally different ways of looking at its job: non- 
preemptive scheduling and preemptive time-slicing. 

NEW*' With non -preemptive scheduling, the scheduler runs the current thread forever, 
TERM requiring that thread explicitly to tell it when it is safe to start a different thread. 
With preempti vetime-sl icing, the scheduler runsthe current thread until ithasused up a certain 
tinyfraction of asecond, and then "preempts” it, suspendosit, and resume os another thread 
for the next tiny fraction of a second. 

N on-preemptive scheduling is very courtly, always asking for permission to schedule, and is 
quite valuable in extremely time-critical, real-time applications where being interrupted at the 
wrong moment, or for too long, could mean crashing an airplane. 

M ost modern schedulers use preemptive time-slicing, because, except for a few time-critical 
cases, it has turned out to makewriting multithreaded programs much easier. Foronething, it 
does not force each thread to decide exactly when it should "yield" control to another thread. 
Instead,everythreadcanjustrun blindly on, knowingthatthescheduler will befair about giving 
all the other threads their chance to run. 

It turns out that this approach isstill nottheideal way to schedule threads. You’ve given a little 
too much control to thescheduler. T hefinal touch many modern schedulers add isto allow you 
to assign each thread a priority. This creates a total ordering of all threads, making somethreads 
more "important" than others. Being higher priority often means that a thread gets run more 
often (or gets more total running time), but it always meansthat it can interrupt other, lower- 
priority threads, even before their "time-slice" has expired. 

T hecurrent J ava release does not precisely specify the behavior of its scheduler. T hreadscan be 
assigned priorities, and when a choice is made between several threadsthat all want to run, the 
highest-priority thread wins. H owever, among threadsthat areal I thesamepriority, thebehavior 
isnot well-defined. In fact, the different platformson which Java currently runs have different 
behaviors- some behaving more like a preemptive scheduler, and some more like a non- 
preemptive scheduler. 
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until you interrupt the program. What if you want to be sure the two threads will take turns, 
no matter what the system scheduler wants to do?You rewrite RunnabiePotato as follows: 

public class RunnabiePotato implements Runnable { 
public void run() { 
while (true) { 

System. out. println(Thread.currentThread() .getName() ) ; 

Thread. yield() ; // let another thread run for a while 



T ip: N ormally you have to say Thread . currentThread ( ) . yield ( ) to get your hands 
on the current thread, and then call yieido. Because this pattern is so common, 
however, the Thread class provides a shortcut. 

The yield o method explicitly gives any other threads that want to run a chance to begin 
running. (If there are no threads waiting to run, the thread that made the yieido simply 
conti nues.) I n our example, there’sanother thread that’sjust dyi ngto run, so when you now run 
the class ThreadTester, it should output the following: 

one potato 
two potato 
one potato 
two potato 
one potato 
two potato 



even if your system scheduler is non-preemptive, and would never normally run the second 
thread. 



PriorityThreadTester 

T o see whether priorities are working on your system, try this: 

public class PriorityThreadTester { 

public static void main(String argv[]) { 

RunnabiePotato aRP = new RunnablePotato( ) ; 

Thread tl = new Thread(aRP, "one potato"); 

Thread t2 = new Thread(aRP, “two potato"); 

t2.setPriority(t1 .getPriorityO +1); 
tl .start(); 

t2.start(); // at priority Thread. NORM_PRIORITY + 1 

} 
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Tip: The values representing the lowest, normal, and highest priorities that threads 
can be assigned are stored in class variables of the Thread class: 

Thread. MIN_PRI0RITY, Thread. N0RM_PRI0RITY, and Thread. MAX_PRI0RITY. The 

system assigns new threads, by default, the priority Thread. norm_priority. Priori- 
ties in Java are currently defined in arangefrom i to 10, with 5 being normal, but 
you shouldn’t depend on these values; use the class variables, or tricks like the one 
shown in this example. 



If one potato is the first line of output, your system does not preempt using priorities. 

W hy? I magi nethat thefi rst thread (ti) hasjust begun to run. Even beforeithasachanceto print 
anything, along comesa higher-priority thread (t2) that wants to run right away. That higher- 
priority thread should preempt (interrupt) thefi rst, and get achanceto print two potato before 
ti finishes printing anything. In fact, if you use the RunnabiePotato class that never yield os, 
t2Staysin control forever, printing two potato lines, because it’s a higher priority than ti and 
it never yields control. If you use the latest RunnabiePotato class (with yieido), the output is 
alternating lines of one potato and two potato as before, but starting with two potato. 

H ere’sagood, illustrative example of how complex threads behave: 

public class ComplexThread extends Thread { 
private int delay; 

ComplexThread (String name, float seconds) { 
super(name) ; 

delay = (int) seconds * 1000; // delays are in milliseconds 

start(); // start up ourself! 

} 

public void run() { 
while (true) { 

System. out . println (Thread. currentThread( ) .get Name ( ) ) ; 
try { 

Thread. sleep(delay) ; 

} catch (InterruptedException ignored) { 
return; 



} 

public static void main(String argv[]) { 



new ComplexThread ( “one potato", 1.1F) 
new ComplexThread ( "two potato", 0.3F) 
new ComplexThread ( "three potato", 0.5F) 
new ComplexThread ( "four" , 0.7F) 
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Thisexamplecombines the thread and itstester into a singleclass. Its constructor takes care of 
nami ng (itself) and of starti ng (itself), becauseit isnow aThread. T hemain < > method createsnew 
instances of its own class, because that class is a subclass of Thread, runo is also more 
complicated, because it now uses, for the first time, a method that can throw an unexpected 
exception. 

T heihread . sieep( ) method forces the current thread to yield ( ) and then waits for at least the 
specified amount of time to elapse before allowing the thread to run again. It might be 
interrupted, however, while sleeping by another thread. In such a case, it throws an 
interruptedException. N ow, because run<) isnotdefined asthrowingthisexception, you must 
"hide" thefact by catching and handling it yourself. Because interruptionsare usually requests 
to stop, you should exit the thread, which you can do by simply returning from the runo 
method. 

Thisprogram should output arepeating but complex pattern of four different lines, whereevery 
oncein awhile you see the following: 

one potato 
two potato 
three potato 
four 

You should study the pattern output to proveto yourself that trueparallelism isgoingon inside 
J ava programs. You may also begin to appreciate that, if even thissimpleset of four threadscan 
produce such complex behavior, many more threads must be capable of producing near chaos 
if not carefully controlled. Luckily, J ava provides the synchronization and thread-safe libraries 
you need to control that chaos. 

Summary 

T oday, you learned that parallelism is desirable and powerful, but introduces many new 
problems- methods and variables now need to be protected from thread conflicts- that can 
lead to chaos if not carefully controlled. 

By "thinking multithreaded,” you can detect the places in your programs that require 
synchronized statements (or modifiers) to make them thread-safe. A series of point examples 
demonstrated thevariouslevelsof safety you can achieveand showed howsubdassesof Thread 

ordassesthatimplementtheRunnabie interface, arecreated and run< ) to gen eratemultithreaded 
programs. 

You also learned how to yield o, howto start o, stopo.suspendo.and resume o yourthreads, 
and how to catch ThreadDeath whenever it happens. 





Multithreading 



Finally, you learned about preemptive and non-preemptive scheduling, both with and without 
priorities, and how to test your Java system to see which of them your scheduler is using. 

This wraps up the description of threads. You now know enough to write the most complex of 
programs: multithreaded ones.Asyou get more comfortablewith threads, you maybegintouse 
theihreadGroup classor to use the enumeration methodsof Thread to get your handson all the 
threads in the system and manipulate them. Don’t be afraid to experiment; you can’t 
permanently break anything, and you learn only by trying. 

Q&A 

Q If they're so important to Java, why haven't threads appeared throughout the 
entire book? 

A Actually, they have. Every stand-alone program written so far has "created” at least 
one thread, the one in which it is running. (Of course the system created that Thread 
for it automatically.) 

Q H ow exactly do these threads get created and run? W hat about applets? 

A W hen a simple, stand-alone J ava program starts up, the system creates a main thread, 
and its run o method calls your main o method to start your program— you do 
nothing to get that Thread. Likewise, when a simple applet loads into ajava-aware 
browser, a Thread has already been created by the browser, and its run o method calls 
yourinito and start o methods to start your program. In either case, anewThreado 
of some kind was done somewhere, by thej ava environment itself. 

Q The ThreadTester class had an infinite loop that created Threads and then 
joinoed with them. Is it really infinite? 

A In theory, yes. In actuality, how far the loop runs determines the resource limits of 
(and tests the stability of) the threads package and garbage collector in yourjava 
release. Overtime, all Java releases will converge on making the loop truly infinite. 

Q I know Java releases are still a little fuzzy about the scheduler's behavior, but 
what's the current story? 

A H ere are the gruesome details for the beta release, relayed by Arthur van H off at Sun: 
the way Java schedules threads "...depends on the platform. It is usually preemptive, 
but not always time-sliced. Priorities are not always observed, depending on the 
underlying implementation.” This final clause gives you a hint that all this confusion 
is an implementation problem, and that someday soon, the design and implementa- 
tion will both be clear about scheduling behavior. 
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Q D oes J ava support more complex multithreaded concepts, such as semaphores? 

A The class object in Java provides methods that can be used to build up condition 
variables, semaphores, and any higher-level parallel construct you might need. The 
method watto (and its two variants with a timeout) causes the current thread to wait 
until some condition has been satisfied. The method notityo (ornotifyAiio), 
which must be called from within asynchronized method or block, tells the thread (or 
all threads) to wake up and check that condition again, because something has 
changed. By careful combi nations of these two primitive methods, any data structure 
can be manipulated safely by a set of threads, and all the classical parallel primitives 
needed to implement published parallel algorithms can be built. 

Q My parallel friends tell me I should worry about something called "deadlock." 
Should I? 

A N ot for simple multithreaded programs. H owever, in more complicated programs, 
one of the biggest worries does become one of avoiding a situation in which one 
thread has locked an object and is waiting for another thread to finish, while that 
other thread is waiting for the first thread to release that same object before it can 
finish. That’s a deadlock— both threads will be stuck forever. M utual dependencies 
like this involving more than two threads can be quite intricate, convoluted, and 
difficult to locate, much less rectify. T hey are one of the main challenges in writing 
complex multithreaded programs. 
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T oday, you’ll explorejava’s streams: 

□ I nput streams- and how to create, use, and detect the end of them— and filtered 
input streams, which can be nested to great effect 
Z 0 utput streams, that are mostly analogous to (but the inverse of) input streams 

You’ll also learn about two stream interfaces that makethe reading and writing of typed streams 
much easier (aswellasabout several utility classesused to accessthefilesystem). Let'sbegin with 
a little history behind the invention of streams. 

One of the early inventions of the U N IX operating system was the pipe. By unifying all these 
disparate ways of communicating into a single metaphor, UNIX paved thewayforawholeseries 
of related inventions, culminating in the abstraction known as streams. 

NEW*' A pipe is an uninterpreted stream of bytes that can be used for communicating between 
TERM programs (or other "forked" copies of your own program) or for reading and writing to 
peripheral devicesand files. 

A stream isapath of communication between thesourceof someinformation and itsdestination. 

That information, an uninterpreted byte stream, can come from any “pipe source," the 
computer’s memory, or even from the Internet. In fact, the source and destination of a stream 
arecompletely arbitrary producers and consumersof bytes, respectively. Therein liesthe power 
of the abstraction. You don’t need to know about the source of the information when reading 
from a stream, and you don’t need to know about the final destination when writing to one. 

General-purpose methods that can read from any source accept a stream argument to specify 
that source; general methods for writing accept a stream to specify the destination. Arbitrary 
processorsforfi Iters) of data havetwo stream arguments. T hey read from thefirst, processthedata, 
and write the results to the second. T hese processors have no idea of either the source or the 
destination of the data they are processing. Sources and destinationscan vary widely: from two 
memory buffersonthesamelocal computer, to theELF transmissionsto and from a submarine 
at sea, to the real-time data streams of a N ASA probe in deep space. 

By decoupling the consuming, processing, or producing of data from the sources and 
destinationsof that data, you can mix and match any combination of them at will as you write 
your program. In the future, when new, previously nonexistent forms of source or destination 
(or consumer, processor, or producer) appear, they can beused within thesameframework, with 
no changes to your classes. N ew stream abstractions, supporting higher levelsof interpretation 
"on top of” the bytes, can be written completely independently of the underlying transport 
mechanisms for the bytes themselves. 
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At the pinnacle of this stream framework are the two abstract classes, mputstream and 
outputstream. Ifyouturn briefly to the diagram for java, to in AppendixB, you’ll seethat below 
these classes is a virtual cornucopia of categorized classes, demonstrating the wide range of 
streams in the system, but also demonstrating an extremely well-designed hierarchy of 
relationships between these streams, onewell worth learning from. Let’sbegin with the parents 
and then work our way down this bushy tree. 

I nput Streams 

All themethodsyou will explore today are declared to throw ioExceptions. This new subclass 
of Exception conceptually embodies all the possible I/O errors that might occur while using 
streams. Several subdassesof it defineafew, morespecificexceptionsthatcan bethrown aswell. 
For now, it is enough to know that you must either catch an ioException, or be in a method 
that can "pass it along,” to be a well-behaved user of streams. 

The abstract Class I nputStream 

mputstream is an abstract class that defines the fundamental ways in which a destination 
consumer reads a stream of bytes from some source. The identity of thesource, and the manner 
ofthecreation and transport of thebytes, isirrelevant. When using an input stream, you are the 
destination of those bytes, and that’s all you need to know. 

read() 

T hemost important method to theconsumer of an input stream istheonethat readsbytesfrom 
thesource. T hismethod, read < ) , comesin manyflavors, and each isdemonstrated in an example 
in today’s lesson. 

Each of these read< ) methodsisdefined to "block” (wait) until all theinput requested becomes 
available. D on’t worry about this limitation; because of multithreading, you can do as many 
other things as you likewhilethisonethread iswaiting for input. In fact, itisacommon idiom 
to assign athread to each stream of input (and for each stream of output) that issolely responsible 
for reading from it (or writing to it). Theseinputthreadsmight then "hand off" theinformation 
to other threads for processing. This naturally overlaps the I/O time of your program with its 
compute time. 

H ere’s the first form of reado: 

InputStream s = getAnInputStreamFromSomewhere( ) ; 

byte[] buffer = new byte [1024]; // any size will do 

if (s.read(buffer) != buffer. length) 

System.out.printlnC'I got less than I expected. 1 '); 
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Note: H ere, and throughout the rest of today’s lesson, assume that either an import 
java.io appears before all the examples or that you mentally prefix all references to 
java.io Classes with the prefix java.io. 



T hisform of read ( ) attemptsto fill the entire buffer given. I f it cannot (usually dueto reaching 
theend of theinput stream), it returnstheactual number of bytesthat were read into thebuffer. 
After that, anyfurthercallstoreado return - 1 , indicating that you are at theend ofthestream. 
N otethat theif statement still works even in thiscase, because -i <= 1024 (this corresponds 
to an input stream with no bytes in it all). 
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Note: Don’t forget that, unlikein C, the -1 casein Java is not used to indicate an 
error. Any I/O errors throw instances of ioException (which you’re not catching 
yet). You learned on Day 17 that all uses of distinguished values can be replaced by 
the use of exceptions, and so they should. The -1 in the last example is a bit of a 
historical anachronism. You’ll soon see a better approach to indicating end of the 
stream using the class Datainputstream. 



You can also read into a "slice" of your buffer by specifying the offset into the buffer, and the 
length desired, as arguments to reado: 

s.read(buffer, 100, 300); 

Thisexampletriestofill in bytesio© through 399 and behavesotherwise exactly thesame as the 
previousreado method. In fact, in thecurrent release, thedefault implementation of theformer 
version of reado uses the latter: 

public int read(byte[] buffer) throws IOException { 
return read(buffer, 0, buffer. length) ; 

> 

Finally, you can read in bytes one at a time: 

InputStream s = getAnInputStreamFromSomewhere() ; 
int byteOrMinusI ; 

while ((byteOrMinusI = s.readO) != -1) { 
b = (byte) byteOrMinusI; 

... // process the byte b 

> 

... // reached end of stream 
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Note: Because of the nature of integer promotion in Java in general, and because in 
this case the read o method returns an mt, using the byte type in your code may 
be a little frustrating. You’ll find yourself constantly having explicitly to cast the 
result of arithmetic expressions, or of mt return values, back to your size. Because 
reado really should be returning a byte in this case, I feel justified in declaring and 
using it as such (despitethe pain) — it makes the size of the data being read clearer. 
In cases wherein you feel the range of a variable is naturally limited to a byte (ora 
short) rather than an mt, please take the time to declare it that way and pay the 
small price necessary to gain the added clarity. By the way, a lot of the Java class 
library code simply stores the result of reado in an mt. This proves that even the 
J ava team is human— s/eryone makes style mistakes. 



skip() 

W hat if you want to skip over some of the bytes in a stream, or start reading a stream from other 
than its beginning? A method similar to reado does the trick: 

if (S.Skip(1024) ! = 1024) 

System.out.println("I skipped less than I expected."); 

Thisskipsoverthenext 1024 bytesin the input stream, skipo takes and returnsalong integer, 
because streamsarenot required to belimited to any particular si zeThedefault implementation 
of skip in this release simply uses read ( ) : 

public long skip(long n) throws IOException { 
byt e [ ] buffer = new byte[(int) n ] ; 

return read(buffer) ; 



N ote: T his implementation does not support large skips correctly, because its long 
argument is cast to an mt. Subclasses must override this default implementation if 
they want to handle this more properly. This won’t be as easy as you might think, 
because the current release of the Java system does not allow integer types larger 
than mt to act as array subscripts. 
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If for some reason you would liketo know how many bytes are in thestream right now, you can 
ask: 



if (s. availableO < 1024) 

System. out. println( "Too little is available right now."); 

Thistellsyouthenumberof bytesthatyou can read o without blocking. Becauseoftheabstract 
natureofthesourceofthesebytes,streamsmayormaynot beableto tell you areasonableanswer 
to thisquestion. For example, somestreams always return 0. U nless you use specific subclasses 
of inputstream that you know providea reasonable answer to thisquestion, it'snot agood idea 
to rely upon this method. Remember, multithreading eliminates many of the problems 
associated with blocking while waiting for a stream to fill again. Thus, one of the strongest 
rationales for the use of avaiiabieo goes away. 



mark() and reset() 

Some streams support the notion of marking a position in thestream, and then later resetting 
the stream to that position to reread the bytes there. Clearly, the stream would have to 
"remember” all those bytes, so there is a limitation on how far apart in a stream the mark and 
its subsequent reset can occur. There’s also a method that asks whether or not the stream 
supports the notion of marking at all. H ere'san example: 

Inputstream s = getAnInputStreamFromSomewhere() ; 

if (s.markSupportedO) { // does s support the notion? 

... // read the stream for a while 

s. mark (1024) ; 

... // read less than 1024 more bytes 

s. reset () ; 

... //we can now re-read those bytes 

> else { 

... // no, perform some alternative 

> 

W hen marking astream, you specify themaximum number of bytesyou intend to allow to pass 
before resetting it. This allows the stream to limit thesize of its byte "memory." If this number 
of bytes goes by and you have not yet reset o, the mark becomes invalid, and attempting to 
reset 0 will throw an exception. 

M arking and resetting a stream is most valuable when you are attempting to identify the type 
of thestream (or the next part of thestream), buttodoso,you must consumeasignificant piece 
of it in the process. Often, this is because you have several black-box parsers that you can hand 
thestream to, but they will consume some (unknown to you) number of bytes before making 
up their mind about whether the stream is of their type. Set a largesizefor theread limit above, 
and let each parser run until it either throws an error or completes a successful parse. If an error 
is thrown, reset 0 and try the next parser. 



close( ) 

Because you don’t know what 531sourcesan open stream rep531sents, nor how to deal with them 
p5operly when you’re finished reading the stream, you must usually explicitly close down a 
stream so that it can release these 531sources. Of course, garbage collection and a finalization 
method candothisforyou, but what if you need to reopen that stream or those resources before 
they have been freed by this asynchronous p5ocess? At best, this is annoying or confusing; at 
worst, it introduces an unexpected, obscure, and difficult-to-track-down bug. Because you’re 
interactingwith theoutsideworld of external 531sources, it'ssafer to beexplicit about when you're 
finished using them: 

InputStream s = alwaysMakesANewInputStream( ) ; 



try { 

... // use s to your heart's content 

> finally { 

s. close () ; 

> 

Get used to this idiom (using finally); it’s a useful way to be sure something (such as closing 
the stream) always gets done. Of course, you’re assuming that the stream isalways successfully 
created. Ifthisisnot always the case, and nun issometimes returned instead, here’s the correct 
way to be safe: 



InputStream s = tryToMakeANewInputStream( ) ; 

if (s ! = null) { 
try { 

} finally { 
s.close() ; 

} 

> 




All input streams descend from the abstract class inputstream. All share in common the few 
methods described so far. Thus, stream s in the previous examples could have been any of the 
more complex input streams described in the next few sections. 



B yteArrayl nputStream 

The"inverse” of someofthepreviousexampleswould betocreatean inputstream from an array 
of bytes. T his is exactly what ByteArrayinputstream does: 

byte[] buffer = new byte[1024]; 
fillWithUsefulDat a (buffer) ; 

Inputstream s = new ByteArrayInputStream(buff er) ; 
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Readersof thenew stream s seeastream 1 024 byteslong, containing thebytesin thearray butter. 
J ust as read ( ) has a form that takes an offset and a length, so does this class’s constructor: 

InputStream s = new ByteArrayInputStream(buffer, 100, 300); 

H ere, the stream is 300 bytes long and consists of bytes 100-399 from thearray butter. 



Note: Finally, you’ve seen your first examples of the creation of a stream. These 
new streams are attached to the simplest of all possible sources of data, an array of 
bytes in the memory of the local computer. 



ByteArrayinputst reams only implement thestandard set of methodsthat all input streamsdo. 
H ere, however, theavaiiabieo method hasa particularly simplejob— it returns 1024 and 300, 
respectively, forthetwo instances of ByteArrayinputstream you created previously, because it 
knowsexactlyhow many bytes are avai I ab I e. Finally, calling reset 0 on aByteArrayinputstream 
resets it to the beginning of the stream (buffer), no matter where the mark is set. 



Filel nputStream 

Oneofthemost common uses of streams, and historically theearliest, isto attach them to files 
in thefile system. H ere, for example, isthe creation of such an input stream on all N IX system: 

InputStream s = new FilelnputStreamf “/some/path/and/f ileName" ) ; 




Caution: Applets attempting to open, read, or write streams based on files in the 
filesystem can cause security violations (depending on the paranoia level set by the 
user of the browser). T ry to create applets that do not depend on files at all, by 
using servers to hold shared information. If that’s impossible, limit your applet’s 
I/O to a single file or directory to which the user can easily assign file access permis- 
sion. (Stand-aloneJ ava programs have none of these problems, of course.) 



You also can create the stream from a previously opened file descriptor: 

int fd = openInputFileInTraditionalUNIXWays() ; 

InputStream s = new FilelnputStream(fd) ; 

I n either case, because it's based on an actual (finite length) file, the input stream created can 
implement available o precisely and can skipo likeachamp (just as ByteArrayinputstream 
can, by the way). In addition, Fiieinputstream knows a few more tricks: 
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FilelnputStream aFIS = new FileInputStream( "aFileName" ) ; 
int myFD = aFIS.getFD() ; 

/* aFIS.finalize() ; */ // will call close() when automatically called by GC 




Tip: T o call the new methods, you must declare the stream variable aFis to be of 
type Fiieinputstream, because plain inputstreams don’t know about them. 



Thefirst isobvious: getFDo returnsthefiledescriptor of thefileon which thestream isbased. 
The second, though, is an interesting shortcut that allows you to create Fiieinputstreams 
without worrying about closing them later. Fiieinputstream’s implementation of tinaiizeo, 
aprotected method, closes thestream. U nlikein thepreviouscontrived examplein comments, 
you almost never can nor should call atinaiizeo method directly. Thegarbage collector calls 
it after noticing that the stream is no longer in use, but before actually destroying the stream. 
T hus, you can go merrily along using thestream, never closing it, and all will bewell.T hesystem 
takes care of closing it (eventually). 

You can get away with this because streams based on files tie up very few resources, and these 
resources cannot beaccidentally reused before garbage col lection (thesewerethethingsworried 
about in thepreviousdiscussion of finalization and close o). Of course, if you were also writing 
to thefile, you would have to be more careful. (Reopening thefiletoo soon after writing might 
make it appear in an inconsistent state because the finalize) )— and thus the close) >— 
might not have happened yet). Just because you don't have to close the stream doesn't mean 
you might not want to do so anyway. For clarity, or if you don’t know precisely what type of 
an inputstreamyou were handed, you might choose to call close o yourself. 

Filterl nputStream 

This "abstract” class simply provides a "pass-through” for all the standard methods of 
inputstream. It holds inside itself another stream, by definition onefurther "down” the chain 
of filters, to which it forwards all method calls. It implements nothing new but allows itself to 
be nested: 

Inputstream s = getAnlnputStreamFromSomewhere)) ; 

FilterlnputStream si = new FilterlnputStream(s) ; 

FilterlnputStream s2 = new FilterInputStream(s1 ) ; 

FilterlnputStream s3 = new FilterInputStream(s2) ; 

... s3. read)) ... 
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W henever a read is performed on the filtered stream S 3, it passes along the request to s2; then 
s2doesthesametosi,andfinallysisasked to providethebyte&Subclassesof Fiiterinputstream 
will, of course, do some nontrivial processing of thebytes as they flow past. T he rather verbose 
form of "chaining" in the previous example can be made more elegant: 

S3 = new FilterInputStream(new FilterInputStream(new FilterlnputStream(s) ) ) ; 

You should use this idiom in your code whenever you can. It clearly expresses the nesting of 
chained filters, and can easily be parsed and “read aloud” by starting at the innermost streams 
and reading outward— each filter stream applying to the one within— until you reach the 
outermost stream s3. 



Note: Fiiterinputstream is called “abstract," rather than abstract, because it is not 
actually declared to be abstract. This means that, as useless as they are, you can 
create instances of Fiiterinputstream directly. The same will hold for its output 
stream "brother" class, described later today. 



Now let’s examine each of the subclasses of Fiiterinputstream in turn. 



B ufferedl nputStream 

This is one of the most valuable of all streams. It implements the full complement of 
i nputst ream’s methods, but it does so by using a buffered array of bytes that acts as a cache for 
futurereading. Thisdecouplestherateandthesizeofthe"chunks’’you'rereadingfromthemore 
regular, larger block sizes in which streams are most efficiently read (from, for example, 
peripheral devices, files in the file system, or the network). It also allows smart streams to read 
ahead when they expect that you will want more data soon. 

B ecause the buffering of Buff eredinputstream isso valuable, and it'salsotheonly class to handle 
marko and reset <) properly, you might wish that every input stream could somehow share its 
valuablecapabilities. Normally, becausethosestream dassesdo not implementthem, you would 
be out of luck. Fortunately, you already saw a way that filter streams can wrap themselves 
"around” other streams. Suppose that you would like a buffered Fiieinputstream that can 
handle marking and resetting correctly. Etvoila: 

InputStream s = new BufferedInputStream(new FileInputStream( "foo" ) ) ; 

You have a buffered input stream based on the file "foo" that can marko and reseto. 

N ow you can begi n to see the power of nesting streams. Any capabi I ity provided by a fi Iter input 
stream (or output stream, as you’ll see soon) can beused by any other, basic stream via nesting. 
Of course, any combi nation of these capabilities, and inanyorder, can beaseasilyaccomplished 
by nesting the filter streams themselves. 
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Data I nputStream 

All the methods that instancesof thisdassunderstand aredefined in a separate interface, which 
both Datainputstream and RandomAccessFiie (another class in java.io) implement. This 
interface is general-purpose enough that you might want to use it yourself in the classes you 
create. It is called Datainput. 



The Data I nput Interface 

When you begin using streams to any degree, you’ll quickly discover that byte streams are not 
a really helpful format into which to force all data. I n particular, the primitive types of thej ava 
languageembody a rather nice way of looking at data, but with thestreamsyou’ve been defining 
thusfar in this book, you could not read data of these types. T he D atal nput interface specifies 
a higher-level set of methodsthat, when used for both reading and writing, can support a more 
complex, typed stream of data. H ere are the set of methods this interface defines: 

void readFully (byte[ ] buffer) throws IOException; 

void readFully (byte[ ] buffer, int offset, int length) throws IOException; 
int skipBytes(int n) throws IOException; 



long 

float 

double 



readBoolean( ) 
readByte() 
readUnsignedByte() 
readShortf) 
readUnsignedShort ( ) 
readChar( ) 
readlnt( ) 
readLong() 
readFloat ( ) 
readDouble( ) 



throws IOException; 
throws IOException; 
throws IOException; 
throws IOException; 
throws IOException; 
throws IOException; 
throws IOException; 
throws IOException; 
throws IOException; 
throws IOException; 



String readLine() throws IOException; 

String readUTF() throws IOException; 



Thefirst three methodsare simply new names for skip o and the two formsof reado you’ve 
seen previously. Each of the next ten methods reads in a primitive type, or its unsigned 
counterpart (useful for using every bit efficiently in a binary stream). T heselatter methods must 
return an integer of a wider size than you might think; because integers are signed in Java, the 
unsigned value does not fit in anything smaller. The final two methods read a newline ( 1 \r • , 

1 \n ■ , or "\r\n") terminated string of characters from the stream— thefirst in ASCII, and the 
second in Unicode. 



N ow that you know what theinterface that Datainputstream implements looks like, let’sseeit 
in action: 



Datainputstream s = new DataInputStream(getNumericInputStream( ) ) ; 



long size = s.readLong() ; // the number of items in the stream 

while (size- - > 0) { 

if (s.readBoolean()) { 



// should I process this item? 
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int anlnteger = s.readlnt(); 

int magicBitFlags = s.readllnsignedShort() ; 

double aDouble = s . readDouble( ) ; 



} 



if 

> 



((magicBitFlags & 0100000) != 0) { 

... // high bit set, do something special 

// process anlnteger and aDouble 



Because the class implements an interface for all its methods, you can also use the following 
interface: 



Datalnput d = new DataInputStream(new FileInputStream( "anything" )) ; 
String line; 



while ((line = d.readLine()) != null) { 
... // process the line 



The EOFException 

0 ne final point about most of Datainputstream’s methods: when the end of the stream is 
reached, they throw an EOFException. This is tremendously useful and, in fact, allows you to 
rewrite all thekludgy uses of -i you saw earlier today in a much nicer fashion: 

DatalnputStream s = new DataInputStream(getAnInputStreamFromSomewhere( ) ) ; 



try { 

while (true) { 

byte b = (byte) s.readByte() ; 
... // process the byte b 

> 

> catch (EOFException e) { 

... // reached end of stream 



} 



T his works just as well for all but the last two of the read methods of Datainputstream. 




Caution: skipByteso does nothing at all on end of stream, readLineo returns 

null, and readUTF() might throw a UTFDataFormatException, if it notices the 

problem at all. 
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LineNumberl nputStream 

In an editor or a debugger, line numbering is crucial. To add this valuable capability to your 
programs, use thefilter stream LineNumberinputstream, which keepstrack of line numbers asits 



stream "flows through" it. It’s even smart enough to remember a line number and later restore 
it, during amarko and reseto. You might use this class as follows: 

LineNumberlnputStream aLNIS; 

aLNIS = new LineNumberInputStream(new FileInputStream( "source" )) ; 

DatalnputStream s = new DatalnputStream(aLNIS) ; 

String line; 

while ((line = s. readLine( ) ) != null) { 

... // process the line 

System.out.println(“Did line number: “ + aLNIS. getLineNumber() ) ; 

> 

H ere, two filter streams are nested around theFiieinputstream actually providing thedata- 
thefirst to readlinesoneatatimeandthesecondto keep track of thelinenumbersof these lines 
astheygoby.You must explicitly nametheintermediatefilter stream, aLNis, becauseif you did 
not, you couldn’t call getLineNumbero later. N otethat if you invert the order of the nested 
streams, reading from theDatalnputStream doesnot cause the LineNumberlnputStream to “see" 
the lines. 

You must put any filter streams acting as "monitors" in themiddleof the chain and “pull" the 
datafromtheoutermost filter stream so that thedata will passthrough each of the monitors in 
turn. Inthesameway, buffering should occur asfarinsidethe chain as possible, becauseit won’t 
beableto do itsjob properly unless most of the streams that need buffering come after it in the 
flow. For example, here’s a doubly silly order: 

new BufferedlnputStreamfnew LineNumberInputStream( 

•new DataInputStream(new FileInputStream( "foo" ) ) ; 

and here’s a much better order: 

new DataInputStream(new LineNumberInputStream( 

•new BufferedlnputStreamfnew FileInputStream( “foo" ) ) ; 

LineNumberinputstreamscan also betold to setLineNumbero, for those few times when you 
know more than they do. 



Pushbackl nputStream 

T hefi Iter stream dasspushbackinputstream iscommonly used in parsers, to "push back” asingle 
character in theinput (after reading it) whiletrying to determine what to do next — asimplified 
version of themarko and reseto utility you learned about earlier. Its only addition to the 
standard set of inputstream methods is unread o, which as you might guess, pretends that it 
never read the byte passed in as its argument, and then gives that byte back as the return value 
Of the next read(). 

T he following is a simple implementation of readLineo using this class: 

public class SimpleLineReader { 
private FilterlnputStream s; 
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public SimpleLineReader(InputStream anIS) { 
s = new DatalnputStream(anlS) ; 

} 



... // other read() methods using stream s 

public String readLine() throws IOException { 
char[] buffer = new char [ 1 00 ] ; 
int offset = 0; 

byte thisByte; 

try { 

loop: while (offset < buffer. length) { 

switch (thisByte = (byte) s.read()) { 

break loop; 
case 1 \r ' : 

byte nextByte = (byte) s.read(); 

if (nextByte != 1 \n ' ) { 

if (!(s instanceof PushbacklnputStream) ) { 
s = new PushbacklnputStream(s) ; 

} 

( (PushbacklnputStream) s) .unread (nextByte) ; 

> 

break loop; 
default : 

buffer[offset++] = (char) thisByte; 
break; 

} 

> 

} catch (EOFException e) { 
if (offset == 0) 
return null; 

> 

return String. copyValueOf (buffer, 0, offset); 

} 

> 

Thisdemonstratesnumerousthings. For the purpose of this example, readLineo is restricted 
to reading the first 100 characters of the line. In this respect, it demonstrates how not to write 
a general-purpose line processor (you should be able to read any size line). It also remindsyou 
how to break out of an outer loop, and how to produce a string from an array of characters (in 
this case, from a "slice" of the array of characters). This example also includes standard uses of 
inputstream’s read 0 for reading bytes one at a time, and of determining the end of thestream 
by enclosing it in a Datalnputstream and catching EOFException. 

0 ne of the more unusual aspects of the example is the way PushbacklnputStream is used. T 0 be 
sure that ■ \n 1 is ignored following '\r' you have to "look ahead” one character; but if it is not 
a ■ \n 1 , you must push back that character. Look at thenext two linesasif you didn’t know much 
about the stream s. The general technique used isinstructive. First, you see whether s isalready 
aninstanceof somekind of PushbacklnputStream. If so, you can simply useit. If not, you enclose 



the current stream (whatever it is) insidea new Pushbackinputstream and use this new stream. 
N ow, let’s jump back into the context of the example. 

Thelinefollowingwantsto call themethod unread o.Theproblemisthatshasa"compile-ti me 
type” of Fiiterinputstream, and thusdoesn't understand that method. T heprevioustwo lines 
have guaranteed, however, that the run-time type of the stream in s ispushbackinputstream, so 
you can safely cast it to that type and then safely call unreado. 



Note: This example was done in an unusual way for demonstration purposes. You 
could have simply declared a Pushbackinputstream variable and always enclosed the 
Datainputstream in it. (Conversely, simpieLineReader’s constructor could have 
checked whether its argument was already of the right class, the way 
Pushbackinputstream did, before creating a new Datainputstream.) T he interesting 
thing about this approach of "wrapping a class only when needed” is that it works 
for any inputstream that you hand it, and it does additional work only if it needs 
to. Both of these are good general design principles. 



All thesubdassesof Fiiterinputstream havenow been described. It’stimeto return tothedirect 
subclasses of Inputstream. 



Pipedl nputStream 

Thisdass, along with its "brother" class Pipedoutputstream, are covered later today (they need 
to be understood and demonstrated together). For now, all you need to know isthat together 
they create a simple, two-way communication conduit between threads. 



Sequencel nputStream 

Suppose you have two separate streams, and you would like to make a composite stream that 
consists of one stream followed by the other (like appending two strings together). This is 
exactly what sequenceinputstream was created for: 

Inputstream si = new FileInputStream( "theFirstPart" ) ; 

Inputstream s2 = new FileInputStream( "theRest" ) ; 

Inputstream s = new SequenceInputStream(s1 , s2); 

... s.read() ... // reads from each stream in turn 

You could have “faked” this example by reading each file in turn— but what if you had to hand 
the composite stream s to some other method that was expecting only a single inputstream? 
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H ere'sanexample(usings)thatline-numbersthetwopreviousfileswithacommon numbering 
scheme: 

LineNumberlnputStream aLNIS = new LineNumberlnputStream(s) ; 

... aLNIS. getLineNumber() ... 






Note: Stringing together streams this way is especially useful when the streams are 
of unknown length and origin, and were just handed to you by someone else. 



What if you want to string together more than two streams? You could try the following: 



Vector v = 
... Hi 
InputStream 
InputStream 
InputStream 



lew Vector() ; 

it up all the streams and add each to the Vector 
si = new SequenceInputStream(v.elementAt(0) , v.elementAt (1 ) ) ; 
s2 = new SequenceInputStream(s1 , v.elementAt (2) ) ; 

S3 = new SequenceInputStream(s2, v.elementAt (3)) ; 



Note: A vector is a growable array of objects that can be filled, referenced (with 
eiementAt ( >) and enumerated. 



H owever, it’s much easier to use a different constructor that sequenceinputstream provides: 

InputStream s = new SequenceInputStream(v.elements( ) ) ; 

Ittakesan enumeration of all thesequencesyou wish to combi neand returnsasinglestream that 
reads through the data of each in turn. 



StringB ufferl nputStream 

stringBufferinputstream is exactly likeByteArrayinputstream, but instead of being based on 
a byte array, it’s based on an array of characters (a string): 

String buffer = "Now is the time for all good men to come..."; 

InputStream s = new StringBufferlnputStream(buffer) ; 

All comments that were made about ByteAmayinputstream apply here as well. (See the earlier 
section on that class.) 
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Note: stringBufterinputstream is a bit of a misnomer, because this input stream is 
actually based on a string. It should really be called stnnginputstream. 



O utput Streams 

Output streams are, in almost every case, paired with a "brother" inputstream that you’ve 
already learned. If an inputstream performs a certain operation, the "brother" outputstream 
performs the inverse operation. You’ll see more of what this means soon. 

T he a bstract C lass O utputStrea m 

outputstream is the abstract class that defines the fundamental ways in which a source 
(producer) writesastream of bytesto somedestination. T heidentity of thedestination, and the 
manner of the transport and storage of the bytes, is irrelevant. When using an outputstream, 
you are the source of those bytes, and that’s all you need to know. 



write() 

T he most important method to the producer of an output stream is the one that writes bytes 
to the destination. This method, writeo, comes in many flavors, each demonstrated in an 
example below. 



Note: Every one of these writeo methods is defined to "block" (wait) until all 
the output requested has been written. You don’t need to worry about this 
limitation— seethe note under inputstream’s read o method if you don’t 
remember why. 



Outputstream s = getAnOutputStreamFromSomewhere() ; 

byte[] buffer = new byte [ 1 024 ] ; // any size will do 

filllnData(buffer) ; // the data we want to output 

s.write(buffer) ; 

You also can write a ”sl ice" of you r buffer by specifyi ng the offset i nto the buffer, and the length 
desired, as arguments to writeo: 

s.write(buffer, 100, 300); 
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T his writes out bytes 1 00 through 399 and behaves otherwise exactly the same as the previous 
write ( ) method. I n fact, in thecurrent release, thedefault implementation of theformer version 
of write 0 uses the latter: 

public void write(byte[] buffer) throws IOException { 
write(buffer, 0, buffer. length) ; 

> 

Finally, you can write out bytes one at a time: 

while (thereAreMoreBytesToOutput()) { 
byte b = getNextByteForOutput() ; 

s.write(b) ; 



flush() 

Becauseyou don’t know what an output stream isconnected to, you might berequi red to "flush” 
your output through some buffered cacheto get it to be written (in a timely manner, or at all), 
outputstream's version of this method does nothing, but it is expected that subclasses that 
requireflushing (for example, Buff eredoutputstream and printstream) will overridethisversion 
to do something nontrivial. 

close() 

J ust likefor an inputstream, you should (usually) explicitly closedown an outputstream so that 
it can release any resourcesit may havereserved on your behalf. (All thesamenotesand examples 
from inputstream’scioseo method apply here, with theprefix in replaced everywhere by out.) 

All output streams descend from the abstract class outputstream. All share the previous few 
methods in common. 

B yteArrayO utputStream 

T he inverse of ByteArrayinputstream, which creates an input stream from an array of bytes, is 
ByteArrayOutputstream, which directs an output stream into an array of bytes: 

Outputstream s = new ByteArrayOutputStream( ) ; 
s.write(123) ; 



T he size of the (internal) byte array grows as needed to store a stream of any length. You can 
provide an initial capacity as an aid to the class, if you like: 

Outputstream s = new ByteArrayOutputStream(1024 * 1024); // 1 Megabyte 
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Note: You’ve just seen your first examples of the creation of an output stream. 

T hese new streams were attached to the simplest of all possible destinations of data, 
an array of bytes in the memory of the local computer. 



0 nee the ByteArrayOutputst ream s hasbeen "filled," it can beoutput to another output stream: 

OutputStream anotherOutputStream = getTheOtherOutputStream( ) ; 

ByteArrayOutputStream s = new ByteArrayOutputStream( ) ; 

fillWithUsefulData(s) ; 
s.writeTo(anotherOutputStream) ; 

1 1 also can be extracted as a byte array or converted to a string: 

byte[] buffer = s.toByteArray() ; 

String bufferstring = s .toString( ) ; 

String bufferUnicodeString = s .toString(upperByteValue) ; 



Note: The last method allows you to "fake" U nicode (16-bit) characters by filling 
in their lower bytes with ASCII and then specifying a common upper byte (usually 
0) to create a U nicode string result. 



ByteArrayOutputstreams have two utility methods: one simply returns the current number of 
bytes stored in the internal byte array, and the other resets the array so that the stream can be 
rewritten from the beginning: 

int sizeOfMyByteArray = s.size(); 

s.reset(); // s.size() would now return 0 
s.write(123) ; 



FileOutputStream 

O ne of the most common uses of streams isto attach them to files in the file system. H ere, for 
example, is the creation of such an output stream on a U N IX system: 

OutputStream s = new FileOutputStream( “/some/path/and/f ileName" ) ; 

\ 

^ Caution: Applets attempting to open, read, or write streams based on files in the 
filesystem can cause security violations. Seethe note under Fiieinputstream for 
more details. 
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You also can create the stream from a previously opened file descriptor: 

int fd = openOutputFileInTraditionalUNIXWays( ) ; 

OutputStream s = new FileOutputStream(fd) ; 

Fiieoutputstream isthe inverse of Fiieinputstream, and it knows the same tricks: 

FileOutputStream aFOS = new FileOutputStream ( "aFileName" ) ; 
int myFD = aFOS.getFD() ; 

/* aFOS.finalize() ; */ // will call closed when automatically called by GC 



a 



Note: To call the new methods, you must declare the stream variable aFos to be of 
type Fiieoutputstream, because plain outputstreams don’t know about them. 



The first is obvious. getFDo simply returns thefile descriptor for thefile on which the stream 
is based. Thesecond, commented, contrived call to finalized isthere to remind you that you 
don’t have to worry about closing the stream— it is done for you automatically. (See the 
discussion under Fiieinputstream for more.) 



F ilterO utputStream 

This "abstract” class simply provides a "pass-through” for all the standard methods of 
outputstream. 1 1 holds inside itself another stream, by definition onefurther"down" thechain 
of filters, to which it forwards all method calls. It implements nothing new but allows itself to 
be nested: 

Outputstream s = getAnOutputStreamFromSomewhere( ) ; 

FilterOutputStream si = new FilterOutputStream(s) ; 

FilterOutputStream s2 = new FilterOutputStream(s1 ) ; 

FilterOutputStream s3 = new Filter0utputStream(s2) ; 

... s3. write (123) ... 

W henever a write is performed on thefiltered stream s3, it passes along the request to s2. T hen 
S 2doesthesameto si, and finallysisasked to output thebytesSubclassesofFiiteroutputstream, 
of course, do some nontrivial processing of the bytes asthey flow past. This chain can be tightly 
nested- see its "brother" class, Fiitennputstream for more. 

Now let's examine each of the subclasses of FilterOutputStream in turn. 
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B ufferedO utputStrea m 

Bufteredoutputstream isoneof the most valuableof all streams. All it doesisimplement thefull 
complement of outputstream’s methods, but it does so by using a buffered array of bytes that 



acts as a cache for writing. T his decouples the rate and the size of the "chunks" you’re writing 
from the more regular, larger block sizes in which streams are most efficiently written (to 
peripheral devices, files in the file system, or the network, for example). 

Bufferedoutputstream isoneof two classes in thejava library to implement fiusho, which 
pushes the bytes you’ve written through the buffer and out the other side. Because buffering is 
so valuable, you might wish that every output stream could somehow be buffered. Fortunately, 
you can surround any output stream in such a way as to achieve just that: 

OutputStream s = new BufferedOutputStream(new FileOutputStream( "foo" ) ) ; 

You now have a buffered outputstream based on the file "foo” that can be flush oed. 

J ust as for filter input streams, any capability provided by a filter output stream can be used by 
any other basic stream via nesting and any combination of these capabilities, in any order, can 
be as easily accomplished by nesting the filter streams themselves. 



D a ta O utputStrea m 

All themethodsthat instancesof this cl ass understand aredefined in a separate interface, which 
both Dataoutputstream and RandomAccessFiie implement. This interface is general-purpose 
enough that you might want use it yourself in the classes you create. It is called Dataoutput. 



The DataOutput Interface 

In cooperation with its "brother” inverse interface, Datainput, Dataoutput provides a higher- 
level, typed-stream approach to thereadingand writing of data. Rather than dealing with bytes, 
this interface deals with writing the primitive types of thej ava language directly: 

void write(int i) throws IOException; 

void write(byte[] buffer) throws IOException; 

void write(byte[] buffer, int offset, int length) throws IOException; 



void 

void 

void 

void 

void 

void 

void 

void 



writeBoolean (boolean 
writeByte(int i) 
writeShort(int i) 
writeChar(int i) 
writelnt(int i) 
writeLong(long 1) 
writeFloat (float f) 
writeDouble (double d) 



b) throws IOException; 
throws IOException; 
throws IOException; 
throws IOException; 
throws IOException; 
throws IOException; 
throws IOException; 
throws IOException; 



void writeBytes (String s) throws IOException; 
void writeChars(String s) throws IOException; 
void writeUTF(String s) throws IOException; 

M ost of these methods have counterparts in the interface Datainput. 

Thefirst three methodsmirror the three formsofwriteo you saw previously. Each of thenext 
eight methods write out a primitive type. Thefinal three methods write out a string of bytes or 
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characters to the stream: the first one as 8-bit bytes; the second, as 16-bit U ni code characters; 
and the last, as a special Unicode stream (readable by Datalnput's reading )), 
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Note: The unsigned read methods in Datainput have no counterparts here. You 
can write out the data they need via Dataoutput’s signed methods because they 
accept mt arguments and also because they write out the correct number of bits for 
the unsigned integer of a given size as a side effect of writing out the signed integer 
of that same size. It is the method that reads this integer that must interpret the 
sign bit correctly; the writer’s job is easy. 



Now that you know what the interface that Dataoutputstream implements looks like, let's see 
it in action: 

DataOutputStream s = new DataOutputStream(getNumericOutputStream( ) ) ; 
long size = getNumberOf ItemsInNumericStream( ) ; 

s.writeLong(size) ; 

for (int i = 0; i < size; ++i) { 
if (shouldProcessNumber(i) ) { 

s.writeBoolean(true) ; // should process this item 

s.writeInt(theIntegerForItemNumber(i) ) ; 
s.writeShort (theMagicBitFlagsForltemNumber(i) ) ; 
s.writeDouble(theDoubleForItemNumber(i) ) ; 

} else 

s.writeBoolean(false) ; 

> 

Thisistheexactinverseof theexamplethatwasgiven for Datainput. Together, they form a pair 
that can communicate a particular array of structured primitive types across any stream (or 
"transport layer”). U se this pair as a jumping-off point whenever you need to do something 
similar. 

In addition to the interface above, the class itself implements one (self-explanatory) utility 
method: 

int theNumberOfBytesWrittenSoFar = s.size(); 



Processing a File 

One of the most common idioms in file I/O istoopen afile, read and process it line-by-line, 
and output it again to another file. H ere’s a prototypical example of how that would be done 
in Java: 

Datainput aDI = new DataInputStream(new FileInputStream( "source" )) ; 

DataOutput aDO = new DataOutputStream(new FileOutputStream( "dest “ ) ) ; 

String line; 
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while ((line = aDI.readLineO) != null) { 

StringBuffer modifiedLine = new StringBuffer(line) ; 

... // process modifiedLine in place 

aDO.writeBytes(modifiedLine.toString() ) ; 

> 

aDI. close () ; 
aDO. close () ; 

If you want to process it byte-by-byte, use this: 

try { 

while (true) { 

byte b = (byte) aDI . readByte ( ) ; 

... // process b in place 

aDO.writeByte(b) ; 

} 

} finally { 

aDI. close () ; 
aDO. close () ; 



H ere's a cute two-liner that just copies the file: 

try { while (true) aDO.writeByte(aDI.readByte()) ; > 
finally { aDI.close(); aDO.close(); } 
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Caution: M any of the examples in today’s lesson (and the last two) assume that 
they appear inside a method that has ioException in its throws clause, so they don’t 
have to "worry” about catching those exceptions and handling them more reason- 
ably. Your code should be a little less cavalier. 




PrintStream 

You maynotrealizeit, butyou’realreadyintimatelyfamiliarwiththeuseoftwo methodsofthe 
printstream class. T hat’s because whenever you use these method calls: 

System. out. print( . . .) 

System. out. println( . . .) 

you areactually using aprintstream in stance located in thesystem’sclassvariableout to perform 
the Output. System. err isalSO a Printstream, and System. in is an InputStream. 



Note: 0 n U N IX systems, these three streams will be attached to standard output, 
standard error, and standard input. 
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Streams 



printstream is uniquely an output stream class (it has no "brother”). Because it is usually 
attached to a screen output device of some kind, it provides an implementation oftiusho. It 
also provides the familiar closed and write o methods, as well as a plethora of choices for 
outputti ng the primitive types and strings of J ava: 



public void 
public void 
public void 
public void 



write(int b) ; 
write(byte[] buffer, int 
flush() ; 
closet) ; 



public void 
public void 
public void 
public void 
public void 
public void 
public void 
public void 
public void 



print(Object o) ; 
print(String s) ; 
print(char[] buffer); 
print(char c) ; 
print(int i) ; 
print(long 1); 
print (float f ) ; 
print(double d) ; 
print(boolean b) ; 






public void 
public void 
public void 
public void 
public void 
public void 
public void 
public void 
public void 



println (Object o) ; 
println(String s) ; 
println(char[ ] buffer); 
println(char c) ; 
println(int i); 
println(long 1); 
println(float f ) ; 
println (double d) ; 
println(boolean b) ; 



length) ; 



public void println(); // output a blank line 

printstream can also be wrapped around any output stream, just like a filter class: 



Printstream s = PrintStream(new FileOutputStream( "foo" ) ) ; 



s.println("Here's the first line of text in the file foo."); 

Ifyou provideasecondargumenttotheconstructorforprmtstreamjtisaboolean that specifies 
whether the stream should auto-flush. If true, a flush o is sent after each character is written 
(or for the three-argument form of write o, after a wholegroup of characters has been written.) 

H ere’s a simple example program that operates like the UN IX command cat, taking the 
standard input, line-by-line, and outputting it to the standard output: 

import java.io.*; // the one time in the chapter we'll say this 



public class Cat { 

public static void main(String args[]) { 

Datalnput d = new DatalnputStream(System.in) ; 
String line; 



try { while ((line = d.readLine()) != null) 
System. out. println(line) ; 



} catch (IOException ignored) { } 



} 

} 



P ipedO utputStream 

Along with Pipedinputstream, this pair of classes supports a UNIX-pipe-like connection 
between two threads, implementing all the careful synchronization that allows this sort of 
"shared queue” to operate safely. T o set up the connection: 

Pipedinputstream sin = PipedInputStream() ; 

PipedOutputStream sOut = PipedOutputStream(sIn) ; 

0 nethread writesto sout, and theother readsfrom sin. By setting up two such pairs, thethreads 
can communicate safely in both directions. 



Related Classes 



Theother classes and interfaces in java.io supplement the streamsto provideacompletel/O 
system. 



TheFiie cl ass abstracts "file” in a platform-independent way. Given afilename, it can respond 
to queries about the type, status, and properties of a file or directory in the file system. 

A RandomAccessFiie iscreated given afile, afilename, orafiledescriptor. Itcombinesin oneclass 
implementations of theDatainput and Dataoutput interfaces, both tuned for "random access" 
to a file in the file system. In addition to these interfaces, RandomAccessFiie provides certain 
traditional U N IX-like facilities, such asseekoing to a random point in the file. 

Finally, thestreamTokenizer class takes an input stream and produces a sequence of tokens. By 
overriding itsvariousmethodsin yourown subclasses, you can create powerful lexical parsers. 




You can learn more about any and all of these cl asses from thefull (online) API descriptions in 
your Java release. 



Summary 

Today, you learned about thegeneral idea of streamsand met inputstreamsbased on bytearrays, 
files, pipes, sequences of other streams, and string buffers, as well as input filters for buffering, 
typing data, line numbering, and pushing-back characters. 

You also mettheanalogous"brother” output streamsfor bytearrays, files, and pipes, and output 
filters for buffering and typing data, and the unique output filter used for printing. 
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Along theway, you becamefami liar with thefundamental methodsallstreamsunderstand(such 
as read o and write o), aswell astheuniquemethodsmanystreamsadd to this repertoire. You 
learned about catching ioExceptions- especially the most useful of them, EOFException. 



Finally, thetwice-usefulDatainput and DataoutputinterfacesforrnedtheheartofRandomAccessFiie, 
one of the several utility classes that round out J ava's I/O facilities. 

Java streams provide a powerful base on which you can build multithreaded, streaming 
interfacesof themost complex kinds, and theprogramsfsuch asH otj ava) to interpret them. T he 
higher-level Internet protocols and services of the future that your applets can build upon this 
base are really limited only by your imagination. 



Q In an early reado example, you did something with the variable byteorMinusi 
that seemed a little clumsy. Isn't there a better way?lf not, why recommend the 
cast later? 

A Yes, there is something a little odd about those statements. You might be tempted to 
try something like this instead: 

while ((b = (byte) s.read()) != -1) { 

... // process the byte b 

> 

The problem with this short-cut occurs when reado returns the value oxff (0377). 
Since this value is signed-extended before the test gets executed, it will appear to be 
identical to the integer value -i that indicates end of stream. Only saving that value in 
a separate integer variable, and then casting it later, will accomplish the desired result. 
The cast to byte is recommended in the note for orthogonal reasons— storing integer 
values in correctly sized variables is always good style (and besides, reado really 
should be returning something of byte size here and throwing an exception for end of 
stream). 

Q What input streams in java. io actually implement marko, resetn, and 

markSupportedO? 

A inputstream itself does — and in their default implementations, markSupportedO 
returns false, marko does nothing, and reset 0 throws an exception. The only input 
stream in the current release that correctly supports marking isBufferedinputstream, 
which overrides these defaults. LineNumberinputstream actually implements marko 
and reset 0, but in the current release, it doesn't answer markSupportedO correctly, so 
it looks as if it does not. 
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Q Why isavaiiabieo useful, if it sometimes gives the wrong answer? 

A First, for many streams, it gives the right answer. Second, for some network streams, 
its implementation might be sending a special query to discover some information you 
couldn’t get any other way (for example, the size of a file being transferred by ftp). I f 
you were displaying a "progress bar” for network or file transfers, for example, 
available o would often giveyou the total size of the transfer, and if it did not— 
usually by returning 0— it would be obvious to you (and your users). 

Q What's a good example use of the Datainput/Dataoutput pair of interfaces? 

A One common use of such a pair is when objects want to "pickle” themselves for 
storage or movement over a network. Each object implements read and write methods 
using these interfaces, effectively converting itself to a stream that can later be recon- 
stituted "on the other end” into a copy of the original object. 
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Native Methods 
and Libraries 



byCharlesL. Perkins 




Native Methods and Libraries 



T oday, you’ll learn all thereasonsyou might (or might not) want to write native methodsin 
Java, about all of Java’s built-in optimizations, and about the tricks you can use to makeyour 
programsfaster. You’ll also learn the procedure for creating, making headers and stubs for, and 
linking native methods into a dynamically loadable library. 

Let's begin, however, with the reasons that you might want to implement native methodsin 
the first place. 

There are only two reasons that you might need to declare some of your methods native, that 
is, implemented by a language other than J ava. 

The first, and by far the best reason to do so, isbecauseyou need to utilize a special capability 
of your computer or operating system that thejavadasslibrarydoesnot already provideforyou. 
Such capabilities include interfacing to new peripheral devices or plug-in cards, accessing a 
different typeof networking, or using a unique, but valuablefeatureof your particular operating 
system. T wo more concrete examples are acquiring real-time audio input from a microphone 
or using 3D "accelerator” hardware in a 3D library. N either of these is provided to you by the 
current J ava environment, so you must implement them outsidej ava, in some other language 
(currently C or any language that can link with C). 

T hesecond, and often illusory reason to implement native methods, isspeed— illusory, because 
you rarely need the raw speeds gained bythisapproach. It’seven more rareto not beableto gain 
that speed-up in other ways (as you’ll see later today). Using native methodsin this case takes 
advantage of the fact that, at present, thej ava release does not perform as well as, for example, 
an optimized C program on many tasks. For those tasks, you can writethe"needsto befast” part 
(critical, inner loops, for example) in C, and still use a larger Java shell of classes to hide this 
"trick” from your users. I n fact, thej ava cl ass library usesthisapproach for certain critical system 
cl asses to raise the overall level of efficiency in thesystem. Asa user of thej ava environment, you 
don’t even know (or see) any results of this (except, perhaps, a few classes or methods that are 
final that might not be otherwise). 

D isadvantages of native Methods 

0 nee you decideyou’d liketo, or must, usenative methodsin your program, this choice costs 
you dearly. Although you gain theadvantagesmentioned earlier, you losetheportability of your 
J ava code. 

Before, you had a program (or applet) that could travel to anyj ava environment in the world, 
now and forever. Any new architectures created— or new operating systems written— were 
irrelevant to your code. All it required was that the (tiny) Java Virtual M achine (or a browser 
that had oneinsideit) be available, and it could run anywhere, anytime— now and in thefuture. 
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N ow, however, you’ve created a library of native code that must be linked with your program 
to makeit work properly. T hefirst thing you I oseisthe ability to "travel” asan applet; you simply 
can’t be one! N o Java-aware browser currently in existence allows native code to be loaded with 
an applet, for security reasonsfand these aregood reasons). T hej avateam has struggled to place 
asmuchaspossibleinto the java packages becausethey are theonly environment you can count 
on asan applet. (Thesun packages, shipped primarily for use with stand-alonejava programs, 
are not always available to applets.) 
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Note: Actually, any classes that anyone writes without native code should beableto 
be loaded with an applet, as long as they depend only on the j ava packages. 

U nfortunately, many of thesun packages contain classes that must use native code 
to provide crucial, missing functionality from the java packages. All these missing 
pieces, and some additional multimedia and sound capabilities, will be added to the 
java packages in the future. (This has been informally promised in discussions I’ve 
had with thej ava team.) 



Losing the ability to travel anywhere across the N et, into any browser written now or in the 
future, isbad enough. What’s worse, now that you can’t bean applet, you have further limited 
yourself to onlythosemachinesthat havehad thej avaVirtual M achineported to their operating 
system. (Applets automatically benefit from the wide number of machines and operating 
systems that any J ava-aware browser is ported to, but now you do not.) 

Even worse, you have assumed something about that machine and operating system by the 
implementation of your native methods. T his often means that you have to write different 
sourcecodefor some(orall) of themachinesand operating systemson which you wantto be able 
to run. You’re already forced, by using native methods, to producea separate binary library for 
every machine and operating system pair in the world (or at least, wherever you plan to run), 
and you must conti nueto do so forever. If changing thesourceisalso necessary, you can see that 
this is not a pleasant situation for you and yourj ava program. 



The Illusion of Required Efficiency 

If, even after thepreviousdiscussion, you must usenative methods anyway, there’s help for you 
later in today's lesson— but what if you’re still thinking you need to use them for efficiency 
reasons? 

You arein agrand tradition of programmersthroughout the (relatively few) agesof computing. 
It is exciting, and intellectually challenging, to program with constraints. If you believe 
efficiency isalways required, it makesyourjob a little more interesting- you get to consider all 





Native Methods and Libraries 



sorts of baroque ways to accomplish tasks, because it is the efficient way to do it. I myself was 
caught up in this euphoria of creativity when I first began programming, but it is creativity 
misapplied. 

W hen you design your program, all that energy and creativity should be directed at thedesign 
of atight, concise, minimal set of classes and methods that are maximally general, abstract, and 
reusable. (I f you think that is easy, look around for a few years and see how bad most software 
is.) If you spend most of yourprogrammingtimeonthinkingandrethinkingthesefundamental 
goals and how to achieve them, you are preparing for the future. A future where software is 
assembled asneeded from small componentsswimmingin aseaof network facilities, and anyone 
can write a component seen by millionsfand reused in their programs) in minutes. If, instead, 
you spend your energy worrying about the speed your software will run right now on some 
computer, you will beirrelevant after thel8 to 36 monthsit will takehardwareto befast enough 
to hide that minor inefficiency in your program. 

Am I saying that you should ignore efficiency altogether? Of course not! Some of the great 
algorithms of computer science deal with solving hard or "impossible" problemsin reasonable 
amounts of time— and writing your programs carelessly can lead to remarkably slow results. 
This, however, can as easily lead to incorrect, fragile, or nonreusable results. If you achieve all 
those other goals first, the resulting software will be clean, will naturally reflect thestructure of 
the problem you’re trying to solve, and thus will beamenableto "speeding up” later. 



Note: There are always cases where you must be fanatical about efficiency in many 
parts of a set of classes. T hej ava class library itself is such a case, as is anything that 
must run in real-time for some critical real-world application (such as flying a 
plane). Such applications are rare, however. 

When speaking of anew kind of programming that must soon emerge, Bill Joy, a 
founder at Sun, likes to invoke thefour S’sof Java: small, simple, safe, and secure. 
The "feel" of thej ava language itself encourages the pursuit of clarity and the 
reduction of complexity. The intense pursuit of efficiency, which increases com- 
plexity and reduces clarity, is antithetical to these goals. 



0 nee you build a solid foundation, debug your classes, and your program (or applet) works as 
you’d like it to, then it’stimeto begin optimizing it. If it’sjust a user interface applet, you may 
need to do nothing at all. The user is very slow compared to modern computers (and getting 
relatively slower every 18 months). The odds are that your applet is already fast enough- but 
suppose it isn’t. 




406 



Built-In Optimizations 

Your nextjobistoseewhether your releasesupportsturning on the "just-in-time" compiler, or 
using the java2c tool. 

T hefirst of these is an experimental technology that, while a method’s bytecodes are running 
in thejava Virtual M achine, translates each bytecode into thenative binary code equivalent for 
the local computer, and then keeps this native code around as a cache for the next time that 
method is run. This trick iscompletely transparent to thejava code you write. You need know 
nothi ng about whether or not it’s bei ng done— your code can sti 1 1 "travel " anywhere, anyti me. 
0 n any system with "just-in-time” technology in place, however, it runsa lot faster. Experience 
with experimental versionsofthistechnologyshowsthat, after paying a small cost thefirsttime 
a method is run, this technique can reach the speed of compiled C code. 



Note: M ore details on this technique, and the java2c tool, will be presented 
tomorrow. As of the beta release, neither of these tools are in thej ava environment, 
but both are expected in the final release. 



Thejava2ctranslatortakesawhole.classfilefullofthebytecodesforaclassandtranslatesthem 
(all at once) into a portable C source code version. This version can then be compiled by a 
traditional C compiler on your computer to produceanative-method-likecached library of fast 
code. This large cache of native code will be used whenever the class’s methods are called, but 
only on thelocal computer. Your original Java codecan still travel as bytecodes and run on any 
other computer system. If the virtual machineautomaticallytakesthesestepswhenever it makes 
sense for a given class, thiscan be as transparent as the "just-in-time” technology. Experience 
with an experimental version of thistool showsthat fully optimized C performanceisachievable. 
(T his is the best anyone can hope to do!) 

So you see, even without taking any further steps to optimize your program, you may discover 
that for your release of J ava (or for releases elsewhere or coming in the near future), your code 
isalready fast enough. If it isnot, remember that theworld craves speed. Java will only get faster, 
thetoolswill only get better. Your codeistheonlypermanentthing in thisnew world— it should 
be the best you can make it, with no compromises. 



Simple O ptimization T ricks 

Supposethat these technologies aren't availableor don’t optimizeyour program far enough for 
your taste. Y ou can profile your applet or program as it runs, to see in which methods it spends 
the most time. 0 nceyou know thiscrucial information, you can begin to maketargeted changes 
to your classes. 
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Tip: U sejava -prof ... to produce this profile information. I n an early release 
(and, presumably, thefinal release) the javaprof tool can "pretty- print" this 
information in a more readable format, (javaprof is not in the beta release— but try 
the latest J ava release’s documentation for details.) 

Before you begin making optimizations, you also may want to save a copy of your 
"dean” classes. As soon as computer speeds allow it (or a major rewrite necessitates 
it), you can revert to these classes, which embody the "best” implementation of 
your program. 



First, identify the crucial few methods that take most of the time (there are almost alwaysjust 
afew, and often just one, thattakeupthemajority of your program'stime). If they contain loops, 
examine the inner loopsto see whether they: call methods that can bemadefinai, call a group 
of methodsthatcan becollapsed intoasinglemethod, orcreateobjectsthatcan be reused rather 
than created anew each loop. 

Ifyou notice that a long chain of, for example, four or more method calls is needed to reach a 
destination method’s code, and this execution path is in one of the critical sections of the 
program, you can "short-circuit” directly to that destination method in the topmost method. 
T his may require adding a new instance variable to reference the object for that method call 
directly. T hisquiteoften violates layering or encapsulation constraints. T hisviolation, and any 
added complexity, is the price you pay for efficiency. 

If, after all these tricks (and the numerous others you should try that have been collected over 
theyearsinto various programming books), yourj ava code is still just too slow, you will have 
to use native methods after all. 



Writing native Methods 



For whatever reasons, you’ve decided to add native methodsto your program. You’ve already 
decided which methods need to be native, and in which classes, and you’re rarin’ to go. 

First, on thej avaside, all you do isdeletethemethod bodies(all the code between the brackets 
{ and > and thebracketsthemselves) of each method you picked and replace them with a single 
semicolon ( ; ).Then add the modifier native to the method’s existing modifiers. Finally, add 
astatic (class) initializer to each dassthat now containsnative methodsto load thenativecode 
library you’re about to build. (You can pick anynameyou like for this library— detailsfollow.) 
You’re done! 



T hat'sall you need to do in Java to specify a native method. Subclasses of any class containing 
your new native methodscan still overridethem, and thesenew methodsare called for instances 
of the new subclasses (just as you’d expect). 

U nfortunately, what needs to be done in your native language environment is not so simple. 



Note: The following discussion assumes that C and UNIX are your language and 
environment. T his means that some of the steps may differ slightly on your actual 
system, but such differences will be outlined in the notes surrounding the native 
method documentation in your release (in the document called Implementing 
N ativeM ethods in the alpha, but folded into the programmer’s tutorial in the 
beta). The following discussion is purposely parallel to this documentation. 



The Example Class 

I magine a version of the J ava environment that does not provide file I/O . Any J ava program 
needing to use the file system would first have to write native methods to get access to the 
operating system primitives needed to do file I/O . 

T hisexamplecombines simplified versionsof two actual J ava library classes, j ava . io . File and 
java.io.RandomAccessFile, into 3 Single new daSS, SimpleFile: 

public class SimpleFile { 

public static final char separatorChar = 1 > 1 ; 

protected String path; 

protected int fd; 

public SimpleFile (String s) { 
path = s; 

} 

public String getFileName() { 

int index = path. lastlndexOf (separatorChar) ; 

return (index < 0) ? path : path.substring(index + 1); 



public String getPath() { 
return path; 



public native boolean open(); 
public native void close(); 

public native int read(byte[] buffer, int length); 
public native int write(byte[] buffer, int length); 
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static { 

System. loadLibrary( "simple" ) ; // runs when class first loaded 

} 



Note: The unusual separatorchar (■>') isused simply to demonstrate what an 
implementation might look like on some strange computer whose file system didn’t 
use any of the more common path separator conventions. Early Xerox computers 
used ■>■ as a separator, and several existing computer systems still use strange 
separators today, so this is not all that farfetched. 



simpieFiieScan be created and used by other methods in the usual way: 

SimpleFile f = new SimpleFile( ">some>path>and>f ileName" ) ; 

f .open() ; 
f .read( . . . ) ; 
f .write(. . .); 
f .close() ; 

T he first thing you notice about simpieFiie’s implementation is how unremarkable the first 
two-thirdsof its] avacodeisll tlooksjustlikeanyother class, with adassand an instancevariable, 
a constructor, and two normal method implementations. Then there are four native method 
declarations. You’ll recognize these, from previous discussions, as being just a normal method 
declaration with the code block replaced by a semicolon and the modifier native added. T hese 
are the methods you have to implement in C code later. 

Finally, there is a somewhat mysterious code fragment at the very end of the class. You should 
recognizethegeneral construct here asastatic initializer. Any code between thebracketsr and 
> is executed exactly once, when the class is first loaded into the system. You take advantage of 
that fact to run something you want to run only once- the loading of the native code library 
you’ll create later today. T his ties together the loading of the class itself with the loading of its 
nativecode. If either failsfor some reason, the other fai I s as wel I , guaranteeing that no "half-set- 
up” version of the class can ever be created. 



Generating Header and Stub Files 

In order to get your hands on Java objects and datatypes, and to be able to manipulate them 
in yourC code, you need to include some special .h files. M ost of these will be located in your 
release directory under the subdirectory called include. (In particular, look at nativeh in that 
directory, and all the headers it points to, if you’re a glutton for detail punishment.) 
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Someof thespecial formsyou need must be tailored to fityourdass’smethodsprecisely.That’s 
where the javah tool comes in. 



Using javah 

T o gen eratetheheadersyou need foryour native methods, firstcornpilesimpieFiie with javac, 
just as you normally would. This produces a file named SimpleFilexIass. T hisfile must be fed 
to the javah tool, which then generates the header file you need (SimpleFileh). 



Tip: If the class handed to javah is inside a package, it prepends the package name 
to the header file name (and to the structure names it generates inside that file), 
after replacing all the dots (.) with underscores (_) in the package’s full name. 
Thus, if simpieFiie is contained in a hypothetical package called 
acme. widgets, tiles, javah generates a header file named 
acme_widgets_files_ SimpleFileh, and the various names within are renamed in a 
similar manner. 

When running javah, you should pass it only the class name itself, and not the 
filename, which has .class on the end. 



The Header File 

H ere’S the output of javah SimpieFiie: 

/* DO NOT EDIT THIS FILE - it is machine generated */ 

#include <native.h> 

/* Header for class SimpieFiie */ 

#ifndef _Included_SimpleFile 
#define _Included_SimpleFile 
struct Hjava_lang_String; 

typedef struct ClassSimpleFile { 

//define SimpleFile_separatorChar 62L 
struct Hjava_lang_String *path; 
long fd; 

> ClassSimpleFile; 

HandleTo(SimpleFile) ; 

extern /‘boolean*/ long SimpleFile_open (struct HSimpleFile *); 

extern void SimpleFile_close( struct HSimpleFile *); 

extern long SimpleFile_read(struct HSimpleFile *,HArrayOfByte *,long); 

extern long SimpleFile_write( struct HSimpleFile *,HArrayOfByte * , long ) ; #endif 
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Note: HandieToo is a "magic” macro that uses the structures created at run-time by 
the stubs you’ll generate later today. 



The members of the struct generated above are in a one-to-one correspondence with the 
variables of your class. 

I n order to "massage” an instanceof your dassgently into theland of C , usethe macro unhand < ) 
(asin"unhandthatObject!”).Forexample,thethis pseudo-variableinj ava appears asa struct 
HsimpieFiie * in theland of C, and to use any variables inside this instance (you), you must 
unhand ( ) yourself first. You’ll see some examples of this in a later section today. 



Using java h -stubs 

T o "run interference" between thej avaworld of 0 bjects, arrays, and other high-level constructs 
and the lower-level world of C , you need stubs. 

NEW** Stubs are pieces of "glue” code that automatically translate arguments and return values 
TERM back and forth between the worlds of J ava and C . 

Stubscan be automatically generated by javah, just liketheheaders. T hereisn't much you need 
to know about thestubsfile, just that it hasto be compiled and linked with theC codeyou write 
to allow it to interfacewith Java properly. A stubsfile(SimpleFile.c) iscreated by running javah 
on your class by using the option -stubs. 



Note: 0 ne interesting side-effect of stub generation is the creation of method 
signatures informally called method descriptions elsewhere. These signatures are 
quite useful- they can be passed to special C functions that allow you to call back 
into thej ava world from C. You can use stub generation to learn what these 
signatures look likefor different method arguments and return values, and then use 
that knowledge to call arbitrary Java methods from within yourC code. (Brief 
descriptions of these special C functions, along with further details, appear later 
today.) 



The Stubs File 

FI ere’sthe result of running javah -stubs simpieFiie: 

/* DO NOT EDIT THIS FILE - it is machine generated */ 
#include <StubPreamble.h> 
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/* Stubs for class SimpleFile */ 

/* SYMBOL: "SimpleFile/open ( )Z" , Java_SimpleFile_open_stub */ 
stack_item *Java_SimpleFile_open_stub(stack_item *_P_, struct execenv *_EE_) { 
extern long SimpleFile_open(void *); 

_P_ [ 0 ] . i = SimpleFile_open(_P_[0] .p) ; 
return _P_ + 1 ; 

> 

/* SYMBOL: "SimpleFile/close ( ) V" , Java_SimpleFile_close_stub */ 
stack_item *Java_SimpleFile_close_stub(stack_item *_P_, struct execenv *_EE_) { 
extern void SimpleFile_close(void *); 

(void) SimpleFile_close(_P_[0] .p) ; 
return _P_; 

> 

/* SYMBOL: "SimpleFile /read ( [BI ) I " , Java_SimpleFile_read_stub */ 
stack_item *Java_SimpleFile_read_stub(stack_item *_P_, struct execenv *_EE_) { 
extern long SimpleFile_read(void *,void *,long); 

_P_ [ 0 ] .i = SimpleFile_read(_P_[0] .p, ( (_P_[ 1 ] . p) ) , ( (_P_[2] . i) ) ) ; 
return _P_ + 1 ; 

> 

/* SYMBOL: "Simple File /write ( [BI ) I “ , Java_SimpleFile_write_stub */ 
stack_item *Java_SimpleFile_write_stub(stack_item *_P_, struct execenv *_EE_) { 
extern long SimpleFile_write(void *,void *,long); 

P [ 0 ] -i = SimpleFile_write(_P_[0] . p, ( ( P_ [ 1 ] . p) ) , ( (_P_[2] .i))); 

return _P_ + 1 ; 

> 

Each comment line contains the method signature for one of the four native methodsyou’re 
implementing. You can use one of these signatures to call into Java and run, for example, a 
subclass’s overriding implementation of one of your native methods. M ore often, you’d learn 
and use a signature to call some useful J ava method from within C to get something donein the 
Java world. 

You do this by calling a special C function in the Java run-time called 
execute_java_dynamic_method(). Its argumentsindudethetarget object ofthemethod call and 
the method's signature. The general form of a fully qualified method si gnatu re isany/package/ 
name/ClassName/methodName( . . . )X. (YOU Can See Several in the last example, wheresimpleFile 
is the class name and there is no package name.) T hex is a letter (or string) that represents the 
return type, and the . . . contains a string that represents each of the argument’s types in turn. 
H ere are the letters (and strings) used, and thetypesthey represent, in the example: r? isarray 
of type T, B is byte, I is int, V is void, and Z is boolean. 

The method cioseo, which takes no arguments and returns void, isrepresented by the string 
"simpieFiie/ciose ov" and itsinverse, open o, that returnsa boolean instead, isrepresented by 
"simpieFiie/open ( ) z." Finally, reado, which takes an array of bytes and an int as its two 
arguments and returns an int, is ”sim P ieFiie/read([Bi)i.” (Seethe "Method Signatures” 
section in tomorrow’s lesson for the full details.) 
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Creating SimpleFileNative.c 

N ow you can, at last, write the C code for your Java native methods. 

The header file generated by javah, SimpleFile.h, gives you the prototypes of the four C 
functionsyou need to implement to makeyour native code complete. You then write someC 
codethat provides thenativefacilities that yourjavadassneedsfinthiscase, somelow-levelfile 
I/O routines). Finally, you assembleall theC codeintoanewfile, indudea bunch of required 
(or useful) .h files, and name it SimpleFileN ativex. FI ere’s the result: 

#include "SimpleFile.h" /* for unhand(), among other things */ 

#include <sys/param.h> /* for MAXPATHLEN */ 

#include <fcntl.h> /* for 0_RDWR and 0_CREAT */ 

#define LOCAL_PATH_SEPARATOR '/' /* UNIX */ 

static void fixSeparators(char *p) { 
for ( ; *p ! = ' \0 ' ; ++p) 

if (*p == SimpleFile_separatorChar) 

*p = LOCAL_PATH_SEPARATOR; 



long SimpleFile_open(struct HSimpleFile *this) { 
int fd; 

char buff er[MAXPATHLEN] ; 

javaString2CString(unhand(this) ->path, buffer, sizeof (buffer) ) ; 
fixSeparators(buffer) ; 

if ((fd = open(buffer, 0_RDWR | 0_CREAT, 0664)) < 0) /* UNIX open */ 

return(FALSE) ; /* or, SignalError( ) could throw an exception */ 
unhand(this) ->fd = fd; /* save fd in the Java world */ 

return(TRUE) ; 



void SimpleFile_close(struct HSimpleFile *this) { 
close(unhand(this) ->fd) ; 
unhand(this) ->fd = -1; 



long SimpleFile_read(struct HSimpleFile *this, HArrayOfByte *buffer, 

— ■ long count) { 

char *data = unhand(buffer) ->body; /* get array data */ 

int len = obj_length(buff er) ; /* get array length */ 

int numBytes = (len < count ? len : count); 

if ((numBytes = read(unhand(this) ->fd, data, numBytes)) == 0) 
return( -1 ) ; 

return(numBytes) ; /* the number of bytes actually read */ 
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long SimpleFile_write(struct HSimpleFile *this, HArrayOfByte ‘buffer, 

** long count) { 

char ‘data = unhand(buffer) ->body; 
int len = obj_length(buffer) ; 

return(write(unhand(this) ->fd, data, (len < count ? len : count))); 

> 

0 nee you finish writing your .c file, compile it by using your local C compiler (usually called 
cc orgee). 0 n somesystems, you may need to specify special compilation flagsthat mean "make 
it relocatable and dynamically linkable." 



Note: If you don’t have a C compiler on your computer, you can always buy one. 
You also could get a copy of the G N U C compiler (gcc), one of the best C compil- 
ers in the world, which runs on almost every machine and operating system on the 
planet. T he best way to get gcc is to buy the ”G N U release” on C D -RO M , the 
profits of which go to support theFreeSoftwareFoundation. You can find both 
theGNU CD-ROM and the Linux CD -ROM (which includesGN U) in select 
places that sell software or technical books, or you can contact theF.S.F. directly. 
TheGNU CD-ROM is a bit pricey, and, though the Linux CD -RO M isvery 
inexpensive, if you can't afford either, or want the latest version and already own a 
CD-ROM , yOU can download the gzip file ftp: //prep.ai.mit . edu/pub/gnu/gcc- 
2 . 7 . 0 . tar. gz, which contains all 7M of the latest gcc release. (If you’d like to make 
a donation to, or buy gcc or its manual from, the F.S.F., you can e-mail them at 
gnu0prep.ai.mit.edu OC Call 617.542.5942.) 



Some Useful Functions 

W hen writing the C code for native implementations, a whole set of useful (internal) macros 
and functionsareavailablefor accessing] avarun-timestructures. (Several of them wereused in 
SimpleFileN ativex.) 




Let’s take a brief digression to understand some of them a little better. 




Warning: Don’t rely on the exact form given for any of the following macrosand 
functions. Because they’re all internal to thejava run-time, they’re subject to change 
at any moment. Check to see what the latest versions of them look like in your Java 
release before using them. 
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Native Methods and Libraries 



1 



Note: The following brief descriptions are taken from an alpha release of Java, 
because descriptions of them for the beta release were not available as of this 
writing. H ow J ava data types map into C types, and vice versa, is detailed in the 
documentation there. Refer to it for more details on that or on any of the sparsely 
documented items below. (M any are listed just to give you a taste of the capabilities 
of the available functions.) 



The following example: 

Object *unhand (Handle *) 
int obj_length(HArray *) 

returnsapointertothedata portion of an object and returns the length of an array. The actual 
pointer type returned is not always object *, but varies, depending on the type of Handle (or 

HArray). 

This example: 

ClassClass *FindClass(struct execenv *e, char *name, bool_t resolve) 
HArrayOfChar *MakeString(char *string, long length) 

Handle *ArrayAlloc(int type, int length) 

findsa class(given itsname), makes an array of charactersof length length and allocates an array 
of the given length and type. 

Use the function: 

long execute_java_dynamic_method(ExecEnv *e, HObject *obj , char *method_name, 

**char *signature, ...); 

to call aj ava method from C . e isNULL to usethecurrent environment. T hetarget of the method 
call is ob j. The method method_name has the given method signature. It can have any number 
of arguments and returns a 32-bit value (int, Handle *, or any 32-bit C type). 

Use the following: 

HObject *execute_java_constructor(ExecEnv *e, char *classname, ClassClass *c, 

**char *signature, ...); 

long execute_java_static_method(ExecEnv *e, ClassClass *c, char *method_name, 

**char ‘signature, ...); 

to call aj ava constructor from C and call a class method from C . c isthe target class; the rest are 

as in executemethod() . 

Calling this: 

SignalError(0, JAVAPKG "ExceptionClassName" , "message"); 



postsajava exception that will bethrown when your native method returns. 1 1 issomewhat like 
thejavacode: 

throw new ExceptionClassName( "message" ) ; 

Finally, here are some useful string conversion functions: 

void javaStringPrint(Hjava_lang_String *s) 
int javaStringLength(Hjava_lang_String *s) 

Hjava_lang_String *makeJavaString(char ‘string, int length) 

char *makeCString(Hjava_lang_String *s) 
char *allocCString(Hjava_lang_String *s) 

Unicode *javaString2unicode(Hjava_lang_String *s, Unicode *buf, int len) 
char *javaString2CString(Hjava_lang_String *s, char *buf, int len) 

The first two methods print a Java string (like system. out. printo), and get its length, 
respectively. ThethirdmakesaJ avastring out of aC string. Thefourth and fifth do thereverse, 
turning a J ava string into a C string (allocated from temporary or heap storage, respectively). 
The final two methods copyj ava strings into preexisting U nicode or ASCII C buffers. 



Compiling the Stubs File 

Thefinal step you need to take in the C world isto compilethestubsfileSimpleFile.c by using 
the same compilation flags you used for SimpleFileN ative.c. 



Note: If you have several classes with native methods, you can include all their 
stubs in the same .c file, if you like. Of course you might want to name it some- 
thing else, such asStubsx, in that case. 



You’re now finished with all theC code that must be written (and compiled) to make your 
loadable native library. 



A Native Library 

N ow you’ll finally be able to tie everything together and create the native library, simple, that 
was assumed to exist at the beginning of today's lesson. 
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Linking It All 

It’s time to link everything you’ve done into a single library file. This looks a little different on 
each system that Java runs on, but here’s the basic idea, in UN IX syntax: 

cc -G SimpleFile.o SimpleFileNative.o -o simple 

The -g flag tells the linker that you're creating a dynamically linkable library; the details differ 
from system to system. 



Note: By naming the library simple, you’re disobeying a U N IX convention that 
dynamic library names should have the prefix lib and the suffix .so (on your system, 
these prefixes and suffixes may differ). You can call your library libsimplaso to 
obey the convention, if you like, but just for the clarity of this example, the simpler 
name is used. 



Using Your Library 

N ow, when thej avaclasssimpieFiie isfirst loaded into your program, thesystem cl ass attempts 
to load the library named simple, which (luckily) you just created. Look back at thej ava code 
for simpieFiie to remind yourself. 

H ow doesit locateit?ltcallsthedynamic linker, which consultsan environment variablenamed 
ld_library_path that tellsit which sequenceof directoriesto search when loading new libraries 
of native code. Because the current directory is in Java’s load path by default, you can leave 
"simple" in the current directory, and it will work just fine. 

Summary 

T oday, you learned about the numerous disadvantages of using native methods, about the 
many ways that J ava (and you) can make your programs run faster, and also about the often 
illusory need for efficiency. 

Finally, you learned the procedure for creating native methods, from both thej ava and theC 
sides, in detail- by generating header files and stubs, and by compiling and linking a full 
example. 

After working your way through today’s difficult material, you’ve mastered one of the most 
complex parts of thej ava language. You now know how thej ava run-time environment itself 
was created, and how to extend that powerful environment yourself, at its lowest levels. 



418 



Asa reward, tomorrow you look "under thehood" to seesomeof thehidden power of J ava, and 
you can just sit back and enjoy the ride. 

Q&A 

Q W hat can I use to supplement the "Implementing N ative M ethods" document 
you recommended? 

A Looking online is highly recommended. N earby and within "I mplementing N ative 
M ethods" is a M akefile, other related build information, and a more detailed version 
of both the next example in this book and its explanation. T his following discussion 
will be enough to get you started on your first native methods. 

Q Does the Java class library need to call System.loadLibraryO to load the built-in 
classes? 

A No, you won’t see any loadLibraryo calls in the implementation of any classes in the 
Java class library. That's because the Java team had the luxury of being able to stati- 
cally link most of their code into thej ava environment, something that really makes 
sense only when you’re in the unique position of providing an entire system, as they 
are. Your classes must dynamically link their libraries into an already-running copy of 
thej ava system. This is, by the way, more flexible than static linking; it allows you to 
unlink old and relink new versions of your classes at any time, making updating them 
trivial. 

Q Can I statically link my own classes into Java like thej ava team did? 

A Yes. You can, if you like, ask Sun M icrosystems for the sources to thej ava run-time 
environment itself, and, as long as you obey the (relatively straightforward) legal 
restrictions on using that code, you can relink the entirej ava system plus your classes. 
Your classes are then statically linked into the system, but you have to give everyone 
who wants to use your program this special version of thej ava environment. Some- 
times, if you have strong enough requirements, this is the only way to go, but most of 
the time, dynamic linking is not only good enough, but preferable. 

Q M y applet needs some key functionality, missing from the J ava library. G iven 
their many disadvantages, I'd like to avoid using native methods. Do I have any 
alternatives? 

A Because it’s still early in the history of J ava, a valid alternative to native methods is to 
try to convince thej ava team that your needed capability is of interest to a broad 
range of futurejava programmers; then they may include it directly into the java 
packages. There are already plans to do this with certain "missing" pieces of function- 
ality, so this may not be as hard a sell as you might think. Start by posting some 
messages to the comp . ian g . j ava newsgroup, to be sure no one else at Sun or elsewhere 
is already doing it, and then see what happens. This is a young, vibrant community of 
enthusiasts; you are not alone. 
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On today, your final day, the inner workings of the Java system will be revealed. 

You’ll find out all about Java’s vision, Java’s virtual machine, those bytecodes you’ve heard so 
much about, that mysterious garbage collector, and why you might worry about security but 
don’t have to. 

Let's begin, however, with the big picture. 



The Big Picture 

T hej avateam isvery ambitious. T heir ultimategoal isnothing lessthan to revolutionizetheway 
software is written and distributed. They've started with thel nternet, where they believe much 
of the interesting software of thefuture will live. 

T o achieve such an ambitious goal, a large fraction of the I nternet programming community 
itself must be marshalled behind a similar goal and given the tools to help achieve it. The Java 
language, with its four S’s (small, simple, safe, secure), and its flexible, net-oriented environ- 
ment, hopes to become the focal point for the rallying of this new legion of programmers. 

T o this end. Sun M icrosystemshasdonesomething rather gutsy. What wasoriginally asecret, 
tens-of-millions-of-dollars research and development project, and 100 percent proprietary, has 
becomeafree, open, and relatively unencumbered technology standard upon which anyonecan 
build. They are literally giving it away and reserving only the rightsthey need to maintain and 
grow the standard. 



Note: Actually, as Sun’s lawyers have more and more time to think, the original 
intentions of thej avateam get further obscured by legal details. It is still relatively 
unencumbered, but its earlier releases were completely unencumbered. Let’s hope 
that this is not a pattern that will continue. 



Any truly open standard must be supported by at least one excellent, freely available "demon- 
stration" implementation. Sun has already shipped an alpha, and now a beta, of one to the 
Internet and plans on a final release soon. In parallel, several universities, companies, and 
individuals have already expressed their intention to duplicate thejava environment, based on 
the open API that Sun has created. 

Several other languages are even contemplating compiling down to Java bytecodes, to help 
support them in becoming a more robust and commonplace standard for moving executable 
content around on the N et. 
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Why It's a Powerful Vision 

0 ne of the reasons this brilliant move on Sun’s part has a real chance of success is the pent-up 
frustration of literally a whole generation of programmers who desperately want to share their 
code with one another. Right now, the computer science world isbalkanized into factions at 
universities and companies all ova the world, with hundreds of languages, dozens of them 
widely used, dividing and separating us all. It'sthe worst sort of T owa of Babel. Java hopes to 
build some bridges and help tear down thattowa. Because it isso simple, because it’sso useful 
for programming over the Intanet, and because the Intanet is so "hot" right now— this 
confluence of forces should help propel J ava onto centastage. 

Itdeservesto be there. It isthe natural outgrowth of ideas that, since the early 1970s inside the 
Smalltalk group at Xaox PARC, have lain relatively dormant in the mainstream. Smalltalk, in 
fact, invented the first object-oriented bytecode interpreta and pioneered many of the deep 
ideas that J ava builds on today. T hose efforts wae not embraced ova the intervening decades 
as a solution to the genaal problems of software, howeva. T oday, with those problems 
becoming so much moreobvious, and with theN et crying out for a new kind of programming, 
the soil isfatile to grow something strongafrom those old roots, something that just might 
spread like wildfire. (I sit a coincidence that Java’s previous intanal names wae G reen and 
OAK?) 

T his new vision of software is one in which the N et becomes an ocean of objects, classes, and 
the open APIs between them. T raditional applications have vanished, replaced by skeletal 
frameworks I ikethe Eiffel tower, into which can befitted anypartsfromthisocean, on demand, 
to suit any purpose. Usa intafaceswill bemixed and matched, built in pieces and constructed 
to taste, wheneva the need arises, by their own usars M enusofchoiceswill befilled by dynamic 
lists of all the choices availablefor that function, at that exact moment, across the entire ocean 
(of theN et). 

1 n such aworld, software distribution isno longa an issue. Softwarewill bee/aywhaeand will 
be paid for viaa plethora of new micro-accounting models, which charge tiny fractionsof cents 
for the parts as they are assembled and used. Frameworks will come into existence to support 
entatainment, business, and the social (cyber-)spaces of the near future. 

This is a dream that many of us have waited all our livesto be a part of. There are tremendous 
challengesto making it all cometrue, but the powerful winds of change we all feel must stir us 
into action, because, at last, thaeisabaseon which to build that dream— Java. 

The J ava Virtual Machine 

T o make visions like this possible, Java must be ubiquitous. It must be able to run on any 
computer and any opaating system— now, and in the future. In ordato achieve this level of 
portability, Java must be vay praise not only about the language itself, but about the 
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environment in which the language lives. You can see, from earlier in the book and Appendix 
B, that thej ava environment includes a generally useful set of packages of classes and a freely 
available implementation of them. This takes care of a part of what is needed, but it is crucial 
also to specify exactly how the run-time environment of Java behaves. 

This final requirement is what has stymied many attempts at ubiquity in the past. If you base 
your system on any assumptions about what is "beneath” the run-time system, you lose. If you 
depend in any way on thecomputer or operating system below, you lose. J ava solvesthisproblem 
by inventing an abstract computer of its own and running on that. 

This "virtual” machine runs a special set of "instructions" called bytecodes that are simply a 
stream offormatted bytes, each of which hasaprecisespecification of exactly what each bytecode 
does to this virtual machine. The virtual machine is also responsible for certain fundamental 
capabilities of Java, such as object creation and garbage collection. 

Finally, in orderto beableto move bytecodes safely across thelnternet, you need a bulletproof 
model of security— and how to maintain it— and a precise format for how this stream of 
bytecodes can be sent from one virtual machine to another. 

Each of these requirements is addressed in today’s lesson. 



Note: This discussion blurs the distinction between the run-time and the virtual 
machine of Java. This is intentional but a little unconventional. Think of the 
virtual machine as providing all the capabilities, even those that are conventionally 
assigned to the run-time. This book uses the words "run-time” and "virtual 
machine" interchangeably. Equating the two highlights the singleenvironment that 
must be created to support J ava. 

M uch of the following description isbased closely on the alpha "Virtual M achine 
Specifications" documents (and the beta bytecodes), so if you delve more deeply 
into the details online, you will cover some familiar ground. 



An Overview 

It is worth quoting the introduction to thej ava virtual machine documentation here, because 
it is so relevant to the vision outlined earlier: 

Thej ava virtual machine specification has a purpose that is both like and unlike 
equivalent documents for other languages and abstract machines. It is intended to 
present an abstract, logical machine design free from the distraction of inconsequential 
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details of any implementation. It does not anticipate an implementation technology, 
or an implementation host. At the same time it gives a reader sufficient information to 
allow implementation of the abstract design in a range of technologies. 

H owever, the intent of the [...] Java project is to create a language!...] that will allow 
the interchange over the I nternet of "executable content," which will be embodied by 
compiled J ava code. T he project specifically does not want J ava to be a proprietary 
language and does not want to be the sole purveyor of J ava language implementations. 
Rather, we hope to make documents like this one, and source code for our implemen- 
tation, freely available for people to use as they choose. 

This vision [...] can be achieved only if the executable content can be reliably shared 
between different J ava implementations. T hese intentions prohibit the definition of 
thej ava virtual machinefrom being fully abstract. Rather, relevant logical elements of 
the design have to be made sufficiently concrete to allow the interchange of compiled 
J ava code. T his does not collapse thej ava virtual machine specification to a descrip- 
tion of a Java implementation; elements of the design that do not play a part in the 
interchange of executable content remain abstract. But it does force us to specify, in 
addition to the abstract machine design, a concrete interchange format for compiled 
Java code. 

Thej ava virtual machine specification consists of the following: 

n The bytecode syntax, including opcode and operand sizes, values, and types, and their 
alignment and endian-ness 

n The values of any identifiers (for example, type identifiers) in bytecodes or in support- 
ing structures 

n T he layout of the supporting structures that appear in compiled J ava code (for 
example, the constant pool) 
n Thej ava .class file format 
Each of these is covered today. 

Despite this degree of specificity, there are still several elements of the design that remain 
(purposely) abstract, including the following: 

1 T he layout and management of the run-time data areas 
1 The particular garbage-collection algorithms, strategies, and constraints used 
n The compiler, development environment, and run-time extensions (apart from the 
need to generate and read valid J ava bytecodes) 

] Any optimizations performed, once valid bytecodes are received 
T hese places are where the creativity of a virtual machine implementor has full rein. 
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The Fundamental Parts 

Thejava virtual machine can be deconstructed into five fundamental pieces: 

Z A bytecode instruction set 
Z A set of registers 
□ ft stack 

Z A garbage-collected heap 
Z An area for storing methods 

These might be implemented by using an interpreter, a native binary code compiler, or even a 
hardware chip— but all these logical, abstract components of the virtual machine must be 
supplied in sameform in every Java system. 



Note: The memory areas used by thejava virtual machine are not required to beat 
any particular place in memory, to be in any particular order, or even to use 
contiguous memory. H owever, all but the method area must be able to represent 
32-bit values (for example, thejava stack is 32 bits wide). 



The virtual machine, and its supporting code, isoften referred to as therun-time environment, 
and when thisbook refers to something being doneat run-time, the virtual machine is what’s 
doing it. 



J ava Bytecodes 

Thejava virtual machine instruction set isoptimized to be small and compact. It isdesigned to 
travel across the N et, and so has traded off speed-of-interpretation for space. (G iven that both 
N et bandwidth and mass storage speeds increase less rapidly than CPU speed, this seems like 
an appropriate trade-off.) 

Asmentioned, J avasourcecodeis"compiled” into bytecodes and stored in a.classfile. 0 n Sun’s 
Java system, this is performed using the javac tool. Itisnot exactly a traditional "compiler,” 
because javac translates source code into bytecodes, a lower-level format that cannot be run 
directly, but must be further interpreted by each computer. Of course, it is exactly this level of 
"indirection” that buys you the power, flexibility, and extreme portability of Java code. 
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N ote: Q uotation marks are used around the word "compiler” when talking about 
javac because later today you will also learn about the "just-in-time" compiler, 
which acts more like the backend of a traditional compiler. The use of the same 
word "compiler” for these two different pieces of Java technology is unfortunate, 
but somewhat reasonable, because each is really one-half (either the front or the 
back end) of a more traditional compiler. 



A bytecode instruction consists of a one-byte opcode that serves to identify the instruction 
involved and zero or moreoperands, each of which may bemore than onebytelong, that encode 
the parameters the opcode requires. 



Note: When operands are more than onebytelong, they are stored in big-endian 
order, high-order byte first. These operands must be assembled from the byte 
M stream at run-time. For example, a 16-bit parameter appears in the stream as two 
' bytes so that its value is tirst_byte * 256 + second_byte. The bytecode instruc- 
tion stream is only byte-aligned, and alignment of any larger quantities is not 
guaranteed (except for "within" the special bytecodes lookupswitch and 
tabieswitch, which have special alignment rules of their own). 



Bytecodes interpret data in the run-time’s memory areas as belonging to afixed set of types: the 
primitive typesyou’ve seen several times before, consisting of several signed integer types (8-bit 
byte, 16-bit short, 32-bit tnt, 64-bit long), one unsigned integer type (16-bit char), and two 
signed floating-point types(32-bit float, 64-bit double), plusthetype "reference to an object" 
(a 32-bit pointer- 1 ike type). Some special bytecodes (for example, thedup instructions), treat 
run-time memory areas as raw data, without regard to type. Thisisthe exception, however, not 
the rule. 



These primitive types are distinguished and managed by the compiler, javac, not by thejava 
run-time environment. These types are not "tagged" in memory, and thus cannot be distin- 
guished at run-time. Different bytecodes are designed to handle each of the various primitive 
types uniquely, and the compi ler carefully chooses from this palette based on its knowledge of 
the actual types stored in thevariousmemory areas. For example, when addingtwo integers, the 
compiler generates an iadd bytecode; for adding two floats, tadd isgenerated. (You’ll see all this 
in gruesome detail later.) 
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Under the Hood 



Registers 

T he registers of the J ava virtual machine are just like the registers inside a "real” computer. 

NEW*' Registers hold the machine’s state, affect its operation, and are updated after each 
TERM bytecode is executed. 

The following arethejava registers: 

□ pc, the program counter, which indicates what bytecode is being executed 

□ optop, a pointer to the top of the operand stack, which is used to evaluate all arith- 
metic expressions 

Z frame, a pointer to the execution environment of the current method, which includes 
an activation record for this method call and any associated debugging information 

□ vars, a pointer to the first local variable of the currently executing method 
The virtual machine defines these registers to be 32 bits wide. 



Note: Because the virtual machine is primarily stack-based, it does not use any 
registers for passi ng or receiving arguments. T his is a conscious choice skewed 
toward bytecode simplicity and compactness. It also aids efficient implementation 
on register-poor architectures, which most of today’s computers, unfortunately, are. 
Perhaps when the majority of C PU s out there are a little more sophisticated, this 
choice will be reexamined, though simplicity and compactness may still be reason 
enough! 

By the way, the pc register is also used when the run-time handles exceptions; catch 
clauses are (ultimately) associated with ranges of the pc within a method’s 
bytecodes. 



The Stack 

TheJ ava virtual machine is stack-based. A Java stack frame is similar to the stack frame of a 
conventional programming language— it holds the state for a single method call. Frames for 
nested method calls are stacked on top of this frame. 

NE W** T he stack is used to supply parameters to bytecodes and methods, and to 
TERM receive results back from them. 
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Each stack framecontainsthree(possibly empty) se8sofdata: the local variablesfor the me8hod 
call, its execution environment, and itsoperand stack. Thesizesof these first two are fixed at the 
start of a method call, but the operand stack varies in size as bytecodes are executed in the 
method. 

Localvariablesarestoredinan array of 32-bit slots, indexed by theregister vans. M osttypestake 
up one slot in the array, but the long and double types each take up two slots. 



N ote: long and double values, stored or referenced via an index N , take up the (32- 
bit) slots N and N +1. These 64-bit values are thus not guaranteed to be 64-bit- 
aligned. Implementors are free to decide the appropriate way to divide these values 
among the two slots. 



The execution environment in a stack frame helps to maintain the stack itself. It contains a 
pointer to the previous stack frame, a pointer to the local variables of the method call, and 
pointersto the stack's current "base” and "top.” Additional debugging information can also be 
placed into the execution environment. 

The operand stack, a 32-bit first-in-first-out (FIFO) stack, is used to store the parameters and 
return valuesof most bytecodeinstructions.Forexample,theiaddbytecodeexpectstwo integers 
to be stored on thetop of thestack. It pops them, addsthem together, and pushes theresulting 
sum back onto thestack. 

Each primitivedata type has unique instructionsthat know how to extract, operate, and push 
back operandsof that type. For example, long and double operandstaketwo "slots” on thestack, 
and thespecial bytecodes that handle these operandstake this into account. It isillegal for the 
types on thestack and the instruction operating on them to be incompatible (javac outputs 
bytecodes that always obey this rule). 



N ote: T he top of the operand stack and the top of the overall J ava stack are almost 
always the same. Thus, "thestack,” refers to both stacks, collectively. 



The Heap 

The heap is that part of memory from which newly created instances (objects) are allocated. 




In Java, the heap is often assigned a large, fixed size when thej ava run-time system is started, 
but on systems that support virtual memory, it can grow as needed, in a nearly unbounded 
fashion. 
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Under the Hood 



Because objects are automatically garbage-collected in Java, programmers do not have to 
(and, in fact, cannot) manually free the memory allocated to an object when they are finished 
using it. 

Java objects are referenced indirectly in the run-time, via handles which are a kind of pointer 
into the heap. 

Because objects are never referenced directly, parallel garbage collectors can be written that 
operate i ndependently of your program, movi ng arou nd objects i n the heap at wi II . You ’I I learn 
more about garbage collection later. 

The Method Area 

Like the compiled code areas of conventional programming language environments, or the 
TEXT segment in all N IX process, the method area stores thejava bytecodes that implement 
almost every method in thejava system. (Remember that some methods might be native, and 
thus implemented, for example, in C.) The method area also stores the symbol tables needed 
for dynamic linking, and any other additional information debuggersor development environ- 
ments which might want to associate with each method’s implementation. 

Because bytecodes are stored as byte streams, the method area is aligned on byte boundaries. 
(The other areas are all aligned on 32-bit word boundaries.) 

The Constant Pool 

I n the heap, each class has a constant pool "attached” to it. U sually created by javac, these 
constants encode all the names (of variables, methods, and so forth) used by any method in a 
class. Thedasscontainsacount of how manyconstantsthereareandan offset that specifies how 
far into the class description itself the array of constants begins. T hese constants are typed by 
using specially coded bytes and have a precisely defined format when they appear in the .class 
f i I e f or a cl ass. L ater tod ay, a I i ttl e of th i s f i I e fo rm at i s covered , bu t everyth ing isfully specified 
by the virtual machine specifications in yourjava release. 

Limitations 

The virtual machine, as currently defined, places some restrictions on legal Java programs by 
virtueofthechoicesit hasmade(somewere previously described, and morewill bedetailed later 
today). 

These limitations and their implications are 

□ 32-bit pointers, which imply that the virtual machine can address only 4G of memory 
(this may be relaxed in later releases) 



430 




□ Unsigned 16-bit indicies into the exception, line number, and local variable tables, 
which limit the size of a method's bytecode implementation to 64K (this limitation 
may be eliminated in the final release) 

pi U nsigned 16-bit indices into the constant pool, which limits the number of constants 
in a class to 64K (a limit on the complexity of a class) 

I n addition, Sun’simplementation of thevirtual machineusesso-called_quick bytecodes, which 
further limit the system. U nsigned 8-bit offsets into objects may limit the number of methods 
in aclassto 256 (thislimit may notexist in thefinal release), and unsigned 8-bit argument counts 
limit thesizeof theargument list to 255 32-bit words. (Although this means that you can have 
up to 255 argumentsof most types, you can haveonly 127 of them if they'reall long or double.) 

Bytecodes in More Detail 

One of the main tasks of the virtual machineisthefast, efficient execution of thejava bytecodes 
in methods. U nlikein the discussion yesterday about generality in Java programs, this is a case 
where speed isof theupmost importance. Everyjava program suffers from a slow implemen- 
tation here, so the run-time must use as many "tricks" as possible to make bytecodes run fast. 
T heonly other goal (or limitation) isthat J ava programmers must not beableto see these tricks 
in the behavior of their programs. 

A J ava run-time implementer must be extremely clever to satisfy both these goals. 



The Bytecode Interpreter 

A bytecode interpreter examines each opcode byte (bytecode) in a method's bytecode stream, 
in turn, and executes a unique action for that bytecode. T his might consume further bytes for 
theoperandsofthebytecodeand might affect which bytecodewill beexamined next. It operates 
like the hardware CPU in a computer, which examines memory for instructionsto carry out in 
exactly the same manner. It is the software CPU of thejava virtual machine. 



Yourfirst, naive attempt to writesuch a bytecode interpreter will almost certainly bedisastrously 
slow. Theinner loop, which dispatchesonebytecodeeach timethrough theloop, isnotoriously 
difficult to optimize. In fact, smart people have been thinking about this problem, inoneform 
or another, for more than 20 years. Luckily, they’ve gotten results, all of which can be applied 
to J ava. 

Thefinal result isthat the interpreter shipped in thecurrentreleaseofjavahasan extremely fast 
inner loop. In fact, on even a relatively slow computer, this interpreter can perform more than 
330,000 bytecodespersecondIThisisreallyquitegood, becausetheC PU in that computer does 
only about 30 times better using hardware. 
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Under the Hood 



T hisinterpreter isfast enough for most J ava programs (and for thoserequi ri ng more speed, they 
can alwaysuse native methods- see yesterday'sdiscussion)- but what if asmart implementor 
wants to do better? 



The "J ust-in-Time" Compiler 

About a decadeago, a really clever trick wasdiscovered by Peter D eutsch whiletrying to make 
Smalltalk run faster. H ecalled it "dynamic translation" during interpretation. Sun callsit "just- 
in-time" compiling. 

The trick is to notice that the really fast interpreter you’ve just written— in C, for example— 
already hasa useful sequenceof native binary codefor each bytecodethat it interprets: thebi nary 
codethat the interpreter itself isexecuting. Because the interpreter has alreadybeen compiled from 
C into native binary code, for each bytecodethat it interprets, it passes through a sequenceof 
native codeinstructionsfor the hardwareCPU on which it is running. By saving a copy of each 
binary instruction as it “goes by,” the interpreter can keep a running log of the binary code it 
itself has run to interpret a bytecode. It can just as easily keep a log of the set of bytecodes 
that it ran to interpret an entire method. 

You takethat log of instructionsand “peephole-optimize" it, just asa smart compiler does. T his 
eliminates redundant or unnecessary instructions from the log, and makes it look just like the 
optimized binary codethat a good compiler might have produced. 



Note: This is where the name compiler comes from, in "just-in-time" compiler, 
but it’s really only the back end of a traditional compiler- the part that does code 
generation. By the way, the front end hereisjavac. 



H ere's where the trick comes in. The next time that method is run (in exactly the same way), 
the interpreter can now simply executedirectly thestored log of binary native code. Because this 
optimizes out the inner-loop overhead of each bytecode, as well as any other redundancies 
between the bytecodes in a method, it can gain a factor of 10 or more in speed. I n fact, an 
experimental version of this technology at Sun has shown that Java programs using it can run 
as fast as compiled C programs. 
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Note: The parenthetical in the last paragraph is needed because if anything is 
different about the input to the method, it takes a different path through the 
interpreter and must be relogged. (There are sophisticated versions of this technol- 
ogy that solve this, and other, difficulties.) The cache of native code for a method 
must be invalidated whenever the method has changed, and the interpreter must 
pay a small cost up front each time a method is run for the first time. H owever, 
these small bookkeeping costs are far outweighed by the amazing gains in speed 
possible. 



Thejava2c Translator 

Another, simpler, trick, which works well whenever you have a good, portable C compiler on 
each system that runsyour program, isto translate the bytecodes into C and then compilethe 
C into binary native code. Ifyou wait until the first use of amethod or class, and then perform 
thisasan "invisible" optimization, itgainsyou an additional speedup overtheapproach outlined 
previously, without thejava programmer needing to know about it. 

Of course, this does limit you to systemswith aC compiler, but as you learned yesterday, there 
areextremely good, freely availableC compilers. I n theory, yourj ava codemight beableto travel 
with its own C compiler, or know where to pull one from the N et as needed, for each new 
computer and operating system it faced. (Because thisviolatessomeof the rules of normal Java 
code movement over the N et, though, it should be used sparingly.) 

I f you’re using J ava, for example, to writea server that lives only on your computer, it might be 
appropriate to use Java for its flexibility in writing and maintaining the server (and for its 
capability of dynamically linking new J ava codeon the fly), and then to run j ava2c by hand to 
translate the basic server itself entirely into native code. You'd link the Java run-time 
environment into that codeso that your server remainsafully capablej ava program, but it’snow 
an extremely fast one. 

In fact, an experimental version of the java2c translator inside Sun shows that it can reach the 
speed of compiled and optimized C code. This is the best that you can hope to do! 
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N ote: U nfortunately, as of the beta release, there is still no publicly available j ava2c 
tool, and Sun’svirtual machine does not perform "just-in-time" compilation. Both 
of these have been promised in a later release. 





Under the Hood 



T he B ytecodes T hem selves 

Let’s look at a (progressively less and less) detailed description of each class of bytecodes. 

For each bytecode, some brief text describes its function, and atextual "picture" of the stack, 
both before and after the bytecode has been executed, isshown. T histext picture will look like 
the following: 

. . . , valuel , value2 => . . . , value3 

This means that the bytecode expects two operands- vaiuei and vaiue 2 — to be on the top of 
thestack, popsthem both off thestack, operateson them to producevaiue3, and pushesvaiue3 
back onto thetop of thestack. You should read each stack from right to left, with the rightmost 
valuebeingthetopofthestack.The. . . isread as"therest of thestack below,” which isirrelevant 
to the current bytecode. All operands on the stack are 32-bit wide. 

Because most bytecodes take their arguments from thestack and place their results back there, 
the brief text descriptions that follow only say something about the source or destination of 
values if they are not on the stack. For example, the description Load integer from local 
variable, meansthat the i nteger is loaded onto thestack, and integer add. intends its integers 
to be taken from— and the result returned to— the stack. 

Bytecodesthat don’t affect control flow simply movethepc onto thenext bytecodethat follows 
in sequence. T hose that do affect the pc say so explicitly. W henever you see bytei , byte2, and 
so forth, it refersto thefirst byte, second byte, and so on, that follow theopcodebyteitself. After 
such a bytecode is executed, the P c automatically advancesover these operand bytesto start the 
next bytecode in sequence. 



Note: The next few sections are in "reference manual style,” presenting each 
bytecode separately in all its (often redundant) detail. Later sections begin to 
collapse and coalesce this verbose style into something shorter, and more readable. 
The verbose form isshown at first because the online reference manuals will look 
more like it, and because it drives home the point that each bytecode "function” 
comesin many, nearly identical bytecodes, oneforeach primitive type in Java. 



Pushing Constants onto the Stack 

bipush ... => . . . , value 

Push one-bytesigned integer, bytei isinterpreted asasigned 8-bit value. Thisvaiue isexpanded 
to an mt and pushed onto the operand stack. 
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sipush ... => . . . , value 

Push two-byte signed integer, bytei and byte2 are assembled into a signed 16-bit value. This 
value is expanded to an mt and pushed onto the operand stack. 

ldcl ... => .... item 

Push item from constant pool, bytei is used as an unsigned 8-bit index into the constant pool 
of the current class. T he item at that index is resolved and pushed onto the stack. 

Idc2 ... => . . . , item 

Push item from constant pool, bytei and byte2 are used to construct an unsigned 16-bit index 
into the constant pool of the current class. The item at that index is resolved and pushed onto 
the stack. 

Idc2w ... => ..., constant -wordl , constant -word2 

Push long or double from constant pool, bytei and byte2 areused to construct an unsigned 16- 
bit index into the constant pool of the current class. The two-word constant at that index is 
resolved and pushed onto the stack. 

aconst_null ... => . . . , null 

Push the nuii object reference onto the stack. 

iconst_m1 ... => . . . , -1 

Push the mt -i onto the stack. 

iconst_<I> ... => . . . , <I> 

Push themt <i> onto the stack. T here are six of these bytecodes, one for each of the integers 

0-5: iconst_0, iconst_1, iconst_2, iconst_3, iconst_4, and iconst_5. 
lconst_<L> ... => ..., <L> -wordl, <L>-word2 

Push the long <l> onto the stack. There are two of these bytecodes, one for each of the integers 
0 and 1: iconstjs, and iconst_i. 

f const_<F> ... => . . . , <F> 

Push thef ioat <f> onto thestack. T herearethreeof these bytecodes, onefor each of theintegers 

0-2: fconst_0, fconst_1, and fconst_2. 
dconst_<D> ... => ..., <D> -wordl, <D>-word2 

Push thedoubie <d> onto thestack. T herearetwo of these bytecodes, onefor each of theintegers 
0 and 1: dconst_0, and dconst_i. 






Under the Hood 



Loading Local Variables onto the Stack 

iload ... => . . . , value 

Load int from local variable. Local variablebytei in thecu rrent J avaframemust contain an mt. 
T he value of that variable is pushed onto the operand stack. 

iload_<l> ... => . . . , value 

Load int from local variable. Local variableo in thecurrentjavaframemust contain an mt. 
T he value of that variable is pushed onto the operand stack. T here are four of these bytecodes, 
one for each of the integers 0-3: iioad_ 0 , iioad_i, iioad_ 2 , and iioad_3. 

Iload ... => ..., value -wordl , value -word2 

Load long from local variable. Local variablesbytei andbytei + 1 in thecurrentjavaframemust 
together contain a long integer. T he values contained in those variables are pushed onto the 
operand stack. 

lload_<L> ... => ..., value -wordl, value -word2 

Load long from local variable. Local variables <l> and <l> + i in thecurrentjavaframemust 
together contain a long integer. The value contained in those variables is pushed onto the 
operand stack. There are four of these bytecodes, one for each of the integers 0-3: iioad_ 0 , 
lload_l, lload_2, and lload_3. 

f load ... => . . . , value 

Load float from local variable. Local variablebytei in thecurrentjavaframemust contain a 
single precision floating-point number. T he value of that variable is pushed onto the operand 
stack. 

f load_<F> ... => . . . , value 

Load float from local variable. Local variables in thecu rrent J avaframemust contain asingle 
precision floating-point number. The value of that variable is pushed onto theoperand stack. 
There are four of these bytecodes, oneforeach of the integers 0-3: fioad_ 0 , fioad_i, fioad_ 2 , 
and f ioad_3. 

dload ... => ..., value-wordl, value-word2 

Load double from local variable. Local variablesbytei and bytei + i in the current Java frame 
must together contain a double precision floating-point number. The value contained in those 
variables is pushed onto the operand stack. 
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Under the Hood 



fstore_<F> . . . , value => . . . 

Store float into local variable, value must be a single precision floating-point number. Local 
variables <f> and <f> + i in the current Java frame are set to value. There are four of these 
bytecodes, one for each of the integers 0 - 3 : tstoreja, tstorej, fstore_2, and fstore_ 3 . 

dstore value -wordl, value -word 2 => . . . 

Storedoubie into local variable, value must beadoubleprecision floating-point number. Local 
variables bytei and bytei + i in the current Java frame are set to value. 

dstore_<D> value -wordl, value -word 2 => . . . 

Storedoubie into local variable, value must beadoubleprecision floating-point number. Local 
variables <d> and <d> + i in the current J ava frame are set to value. T here are four of these 
bytecodes, one for each of the integers 0 - 3 : dstore_0, dstorej, dstore_2, and dstore_ 3 . 

astore . . . , handle => . . . 

Store object reference into local variable, handle must be a return address or a reference to an 
object. Local variable bytei in the current J ava frame is set to value. 

astore_<A> . . . , handle => . . . 

Store object reference into local variable, handle must be a return address or a reference to an 
object. Local variable <a> in the current Java frame is set to value. There are four of these 
bytecodes, one for each of the integers 0 - 3 : astore_0, astorej, astore_2, and astore_ 3 . 

iinc -no change- 

I ncrement local variableby constant. Local variablebytei in thecu rrentj ava framemust contain 
an mt. Its value is incremented by the value byte2, where byte2 is treated as a signed 8 -bit 
quantity. 

Managing Arrays 

newarray ..., size => result 

Allocate new array, size must bean int. It represents thenumber of elements in the new array, 
bytei isan internal codethatindicatesthe type of array to allocate. Possiblevaluesfor bytei are 

as follows: T_BOOLEAN (4), T_CHAR (5), T_FLOAT ( 6 ), T_DOUBLE (7), T_BYTE ( 8 ), T_SHORT (9), T_INT 

(10), and t_long (11). 

An attempt is made to allocate a new array of the indicated type, capable of holding size 
elements. This will be the result. If size is less than zero, a NegativeArraySizeException is 
thrown. If thereisnot enough memoryto allocate thearray, anoutofMemoryErroristhrown.AII 
elements of the array are initialized to their default values. 
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Under the Hood 



Note: new int [6] [3] [ ] generates these bytecodes: 

bipush 6 
bipush 3 

multianewarray <Class " [ [ [ I " > 2 

It’s more efficient to use newarray or anewarray when creating arrays of single 
dimension. 



arraylength . . . , array => . . . , length 



Get length of array, array must be a reference to an array object. The length of the array is 
determined and replacesamay onthetop of the stack. If array is null, aNullPointerException 
is thrown. 



iaload 

laload 

faload 

daload 

aaload 

baload 

caload 

saload 



array, index => 
array, index => 
array, index => 
array, index => 
array, index => 
array, index => 
array, index => 
array, index => 



value-wordl, value-word2 
value 

value-wordl, value-word2 

value 

value 

value 

value 



Load <type> from array, array must bean array of <type> s. index must bean mt. The <type> 
value at position number index in array is retrieved and pushed onto the top of the stack. If 
array iSnull, aNullPointerException isthrown. If index isnot within the bOUndSOf array, an 
ArraylndexOutOfBoundsException isthrown. <type> is, in turn, int, long, float, double, Object 
reference, byte, char, and short. <type>siong and double have two word values, asyou’veseen 
in previous load bytecodes. 



iastore ..., array, index, value => . . . 

lastore ..., array, index, value-wordl, value-word2 => . . . 

fastore ..., array, index, value => ... 

dastore ..., array, index, value-wordl, value-word2 => . . . 

aastore ..., array, index, value => . . . 

bastore ..., array, index, value => . . . 

castore ..., array, index, value => . . . 

sastore ..., array, index, value => . . . 

Store into <type> array, array must bean array of <type> s, index must bean integer, and value 
a <type>. The <type> value is Stored at position index in array. If array is null, a 
NuiiPointerException is thrown. If index is not within the bounds of array, an 
ArraylndexOutOfBoundsException isthrown. <type> is, in turn, int, long, float, double, Object 
reference, byte, char, and short. <type>siong and double have two word values, asyou’veseen 
in previous store bytecodes. 
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Stack Operations 

nop -no change- 

DO nothing. 

pop . . . , any => . . . 

Pop the top word from the stack. 

pop2 . .., any2, anyl => . . . 

Pop the top two words from the stack. 

dup any => ..., any, any 

Duplicate the top word on the stack. 

dup2 . .., any2, anyl => ..., any2, anyl, any2,any1 

Duplicate the top two words on the stack. 

dup_x1 ..., any2, anyl => ..., anyl, any2,any1 

Duplicate the top word on the stack and insert the copy two words down in the stack. 

dup2_x1 ..., any3, any2, anyl => ..., any2, anyl, any3,any2,any1 

D uplicate the top two words on the stack and i nsert the copies two words down in the stack. 

dup_x2 ..., any3, any2, anyl => ..., anyl, any3,any2,any1 

Duplicate the top word on the stack and insert the copy three words down in the stack. 

dup2_x2 ..., any4, any3, any2, anyl => ..., any2, anyl, any4,any3,any2,any1 

D uplicate thetop two wordson thestack and insert the copies three wordsdown in thestack. 

swap ..., any2, anyl => ..., anyl, any2 

Swap the top two elements on the stack. 

Arithmetic Operations 

iadd ..., vl , v2 => ..., result 

ladd ..., vl -wordl , vl -word2, v2-word1, v2-word2 => ..., r-wordl, r-word2 

fadd . . . , vl , v2 => . . . , result 

dadd ..., vl -wordl , v1-word2, v2-word1, v2-word2 => ..., r-wordl, r-word2 

vi and v2 must be <type>s. The vs are added and are replaced on thestack by their<type> sum. 
<type> is, in turn, int, long, float, and double. 
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isub . . . , vl , v2 => . . . , result 

lsub vl -wordl , v1-word2, v2-word1, v2-word2 => r-wordl, r-word2 

f sub . . . , vl , v2 => . . . , result 

dsub vl -wordl , v1-word2, v2-word1, v2-word2 => r-wordl, r-word2 

vi and v2 must be<type>s. v2 is subtracted from vt, and both vs are replaced on the stack by 
their <type> difference. <type> is, in turn, mt, long, float, and double, 
imul . . . , vl , v2 => . . . , result 

lmul ..., vl -wordl , v1-word2, v2-word1, v2-word2 => ..., r-wordl, r-word2 

fmul . . . , vl , v2 => . . . , result 

dmul ..., vl -wordl , v1-word2, v2-word1, v2-word2 => ..., r-wordl, r-word2 

vi and v2 must be<type>& Both vsare replaced on thestack by their<type> product. <type> is, 
in turn, int, long, float, and double, 
idiv . . . , vl , v2 => . . . , result 

ldiv ..., vl -wordl , v1-word2, v2-word1, v2-word2 => ..., r-wordl, r-word2 

fdiv . . . , vl , v2 => . . . , result 

ddiv ..., vl -wordl , v1-word2, v2-word1, v2-word2 => ..., r-wordl, r-word2 

vi and v2 must be<type>s. v2 is divided by vi, and both vsare replaced on thestack by their 
<type> quotient. An attempt to divideby zero resultsin an ArithmeticException being thrown. 
<type> is, in turn, int, long, float, and double, 
irem . . . , vl , v2 => . . . , result 

lrem ..., vl -wordl , v1-word2, v2-word1, v2-word2 => ..., r-wordl, r-word2 

frem ..., vl , v2 => ..., result 

drem ..., vl -wordl , v1-word2, v2-word1, v2-word2 => ..., r-wordl, r-word2 

vi and v2 must be<type>s. v2 is divided by vi, and both vsare replaced on thestack by their 
<type> remainder. An attempt to divide by zero results in an ArithmeticException being 
thrown. <type> is, in turn, int, long, float, and double, 
ineg ..., value => ..., result 

lneg ..., value-wordl, value-word2 => ..., result-wordl , result -word2 

f neg . . . , value => . . . , result 

dneg ..., value-wordl, value-word2 => ..., result-wordl, result -word2 

value must bea<type>. It is replaced on thestack by its arithmetic negation. <type> is, in turn, 

int, long, float, and double. 



Note: Now that you’re familiar with the look of the bytecodes, the summaries that 
follow will become shorter and shorter (for space reasons). You can always get any 
desired level of detail from the full virtual machine specification in the latest J ava 
release. 
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Logical Operations 

ishl . . . , vl , v2 => . . . , result 

lshl vl -wordl , vl -word2, v 2 => r-wordl, r-word2 

ishr . .., vl , v2 => . .., result 

lshr . .., vl -wordl , v1-word2, v2 => r-wordl, r-word2 

iushr vl, v2 => ..., result 

lushr ..., vl -wordl , vl -word2, v2-word1, v2-word2 => ..., r-wordl, 

For types mt and long: arithmetic shift-left, shift-right, and logical shift-right. 



r-word2 









. . . , vl , v2 => . . . , result 

..., vl -wordl , v1-word2, v2-word1, v2-word2 

. . . , vl , v2 => . . . , result 

..., vl -wordl , v1-word2, v2-word1, v2-word2 

. . . , vl , v2 => . . . , result 

..., vl -wordl , v1-word2, v2-word1, v2-word2 



For types mt and long: bitwise and, or, and xor. 



r-wordl, r-word2 
r-wordl, r-word2 
r-wordl, r-word2 



Conversion Operations 



i21 
i2f 
i2d 
12i 
12f 
12d 
f2i 
f 21 
f2d 
d2i 
d21 
d2f 



value => ..., result -wordl , 
value => . . . , result 
value => ..., result -wordl , 
value -wordl, value -word2 => 
value -wordl, value -word2 => 
value -wordl, value -word2 => 
value => . . . , result 
value => ..., result -wordl , 
value => ..., result -wordl , 
value -wordl, value -word2 => 
value -wordl, value -word2 => 
value -wordl, value -word2 => 



result -word2 

result -word2 
. . . , result 
. . . , result 
. . . , result -wordl , 

result -word2 
result -word2 

. . . , result -wordl , 
. . . , result 



result -word2 



result -word2 



int2byte 

int2char 

int2short 



value => . . . , result 
value => . . . , result 
value => . . . , result 



T hese bytecodes convert from a value of type <ihs> to a result of type <rhs>. <ihs> and <rhs> 
can beany of i, 1, f,and d, which represent int, long, float, and double, respectively. The final 
three bytecodes have types that are self-explanatory. 



Transfer of Control 



ifeq 
ifne 
iflt 
ifgt 
if le 
ifge 



value => 
value => 
value => 
value => 
value => 
value => 



if_icmpeq 

if_icmpne 

if_icmplt 



valuel , value2 => . . . 
valuel , value2 => . . . 
valuel , value2 => . . . 
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if_icmpgt 

if_icmple 

if_icmpge 



, valuel , value2 => 
, valuel , value2 => 
, valuel , value2 => 



ifnull 






ifnonnull 



When value <rel> 0 istrueinthefirst set of bytecodes, valuel <rel> value 2 istrueinthesec 0 nd 
set, or value is null (or not null) in the third, bytei and byte 2 are used to construct a signed 
16-bit offset. Execution proceeds at that offset from the pc. Otherwise, execution proceeds at 
thebytecodefollowing. <rei> isoneofeq, ne, it, gt, ie, and ge, which represent equal, notequal, 
less than, greater than, less than or equal, and greater than or equal, respectively. 

lcmp ..., vl -wordl , v1-word2, v2-word1, v2-word2 => ..., result 

tempi . . . , vl , v2 => . . . , result 

dcmpl ..., vl -wordl , v1-word2, v2-word1, v2-word2 => ..., result 

f empg . . . , vl , v2 => . . . , result 

dempg ..., vl -wordl , v1-word2, v2-word1, v2-word2 => ..., result 

vi and v 2 must be long, float, or double. T hey are both popped from the stack and compared. 
If vl is greater than v 2 , the int valuei is pushed onto the stack. If vi is equal to v 2, 0 is pushed 
onto the stack. If vi is lessthan v 2 , -1 is pushed onto the stack. For floating-point, if either vi 
or V 2 iSNaN, -1 is pushed onto the stack for the first pair of bytecodes , +1 for the second pair. 

if_acmpeq . . . , valuel , value2 => . . . 

if_acmpne . . . , valuel , value2 => . . . 

Branch if object references areequal/not equal, vaiuei and va iue 2 must be references to objects. 
They are both popped from the stack. If vaiuei is equal/not equal to vaiue 2 , bytei and byte 2 
are used to construct a signed 16-bit offset. Execution proceeds at that offset from the pc. 
Otherwise, execution proceeds at thebytecodefollowing. 

goto -no change- 

goto_w -no change - 



Branch always, bytei and byte 2 (plusbyte3 and byte4 for goto_w) areused to construct a signed 
16-bit (32-bit) offset. Execution proceeds at that offset from the pc. 



Jump subroutine. Theaddressofthebytecodeimmediately following thejsrispushed onto the 
stack, bytei and byte 2 (plus byte3 and byte4 for goto_w) are used to construct a signed 16-bit 
(32-bit) offset. Execution proceeds at that offset from the pc. 



Return from subroutine. Local variablebytei (plusbyte 2 are assembled into a 16-bit index for 
ret_w) in thecurrentjavaframemust contain areturn address. Thecontentsofthat local variable 
are written into the pc. 




return-address 

return-address 



ret 

ret2_w 



-no change- 
-no change- 



N ote: j sr pushes the address onto the stack, and ret gets it out of a local variable. 
This asymmetry is intentional. T he jsr and ret bytecodes are used in the imple- 
mentation of Java’s finally keyword. 



Method Return 

return . . . => [empty] 

Return (void) from method. All valuesontheoperand stack arediscarded.Theinterpreter then 
returns control to its caller. 

ireturn ..., value => [empty] 

lreturn ..., value-wordl, value-word2 => [empty] 

freturn ..., value => [empty] 

dreturn ..., value-wordl, value-word2 => [empty] 

areturn ..., value => [empty] 

Return <type> from method, value must bea<type>. The value ispushed onto the stack of the 
previous execution environment. Any other values on the operand stack are discarded. The 
interpreter then returns control to its caller. <type> is, in turn, mt, long, float, double, and 
object reference. 



N ote: T he stack behavior of the "return” bytecodes may be confusing to anyone 
expecting thejava operand stack to be just liketheC stack. Java’s operand stack 
actually consists of a number of discontiguous segments, each corresponding to a 
method call. A return bytecode empties thejava operand stack segment corre- 
sponding to the frame of the returning call, but does not affect the segment of any 
parent calls. 



Table J umping 

tableswitch . . . , index => . . . 

tabieswitch is a variable-length bytecode. Immediately after the tableswitch opcode, zero to 
three 0 bytes are inserted as paddi ng so that the next byte begi ns at an add ress that is a multi pie 
of four. Aft erthepaddingareaseriesof si gned4-bytequantities: default -off set, low, high, and 
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then (high - low + i) further signed 4- byte offsets. These offsets are treated asao-basedjump 
table. 

Theindex must bean int.lfmdexislessthan lowormdexisgreaterthan high, default -offset 
isadded to the pc. Otherwise, the (index - lowj'th element of thejump table isextracted and 
added to the pc. 

lookupswitch .... key => . . . 

lookupswitch isavari able-length bytecode. I mmediately after the lookupswitch opcode, zero to 
threeo bytes are inserted aspadding so that the next bytebeginsat an address that isa multiple 
of four. I mmediately after the padding isa series of pairs of signed 4-byte quantities. T hefirst 
pair is special; it contains the default-offset and the number of pairs that follow. Each 
subsequent pair consists of a match and an offset. 

T he key on the stack must be an mt. T his key iscompared to each of the matches. If it is equal 
to one of them, the corresponding offset is added to the pc. I f the key does not match any of 
the matches, the default -offset is added to the pc. 

Manipulating Object Fields 

putfield ..., handle, value => . . . 

putfield ..., handle, value -wordl , value -word2 => . . . 

Set field in object, bytei and byte2 areused to construct an index into theconstant pool of the 
current class. The constant pool item isafield reference to a cl ass name and afield nameThe 
item is resolved to afield block pointer containing the field’swidth and offset (both in bytes). 

T hefield at that offset from thestart of the instance pointed to by handle will beset to thevaiue 
on thetop of thestack.T hefirst stack pictureisfor 32-bit, and thesecond for 64-bit widefi elds. 
Thisbytecodehandles both. If handle isnuii,aNuiiPointerExceptionisthrown. I fthespecified 
field isa static field, an IncompatibleClassChangeError isthrown. 

getf ield . . . , handle => . . . , value 

getfield ..., handle => ..., value-wordl, value-word2 

Fetch field from object, bytei and byte2 areused to construct an index into theconstant pool 
of thecurrent class. Theconstant pool item will bea field reference to a class name and afield 
name. Theitem is resolved to afield block pointer containing thefield'swidth and offset (both 
in bytes). 

handle must be a referenced an object. Thevaiue at offset into the object referenced by handle 
replaces handle on thetop of the stack. The first stack picture is for 32-bit, and thesecond for 
64-bit wide fields. This bytecode handles both. If the specified field is a static field, an 

IncompatibleClassChangeError isthrown. 
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putstatic . . . , value => . . . 

putstatic value -wordl , value -word2 => . . . 

Set static field in class, bytei and byte2 are used to construct an index into the constant pool of 
the current class. The constant pool item will beafield reference to a static field ofaclass.That 
field will beset to havethevaiue on thetop of thestack. T hefirst stack pictureisfor 32-bit, and 
thesecond for 64-bitwidefields.Thisbytecodehandles both. Ifthespecified field isnot astatic 
field, an IncompatibleClassChangeError is thrown. 

getstatic ..., => ..., value_ 

getstatic ..., => ..., value -wordl, value -word2 

G et static field from class, bytei and byte2 areused to construct an index into theconstant pool 
of thecurrent class. T heconstant pool item will beafield referenced astatic field of adass. T he 
value of that field is placed on thetop of the stack. T hefirst stack picture isfor 32-bit, and the 
second for 64-bit wide fields. This bytecode handles both. I f the specified field is not a static 

field, an IncompatibleClassChangeError is thrown. 

Method Invocation 

invokevirtual . .., handle, [argl, arg2, ...]], ... => ... 

Invoke instance method based on run/time. The operand stack must contain a referenced an 
object and some number of arguments, bytei and by te2 are used to con struct an index into the 
constant pool of thecurrent class. The item at that index in theconstant pool contains the 
complete method signature. A pointer to the object’s method table is retrieved from theobject 
reference. The method signature is looked up in the method table. T he method signature is 
guaranteed to exactly match one of the method signatures in the table. 

T heresult of the lookup isan index into themethod tableofthenamed class that's used to look 
in themethod table of the object's run/timetype, whereapointer to themethod block for the 
matched method is found. Themethod block indicates thetypeof method (native, synchro- 
nized, and so on) and the number of arguments (nargs) expected on the operand stack. 

If themethod is marked synchronized, the monitor associated with handle is entered. 

The base of the local variables array for the new J ava stack frame is set to poi nt to handle on the 
stack, making handle and thesupplied arguments (argi, arg2, . . .) thefirst nargs local variables 
of the new frame. T he total number of local variables used by themethod is determined, and 
theexecution environment of thenewframeispushed after leaving sufficient room forthelocals. 
The base of the operand stack for this method invocation is set to the first word after the 
execution environment. Finally, execution continues with thefirst bytecode of the matched 
method. 

If handle isnuii, a NuiiPointerException is thrown. If during the method invocation a stack 
overflow is detected, astackovertiowError is thrown. 
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invokenonvirtual . .., handle, [argl, arg2, ...]] ... => ... 

Invoke instance method based on compile-time type. The operand stack must contain a 
reference (handle) to an object and some number of arguments, bytei and byte 2 are used to 
construct an index into the constant pool of the current class. The item at that index in the 
constant pool contains the complete method signature and class. The method signature is 
looked up in the method table of the class indicated. The method signature is guaranteed to 
exactly match one of the method signatures in the table. 

T he result of the lookup is a method block. T he method block indicates the type of method 
(native, synchronized, and so on) and the number of arguments (nargs) expected on the 
operand stack. (The last three paragraphs are identical to the previous bytecode.) 

invokestatic ..., , [argl, arg2, ...]] ... => ... 

Invoke class (static) method. The operand stack must contain some number of arguments, 
bytei and byte 2 are used to construct an index into the constant pool of thecurrent class. The 
item at that index in the constant pool contains the complete method signature and class. The 
method signatureislooked upinthemethod tableofthedassindicated.Themethod signature 
is guaranteed to match one of the method signatures in the class’s method table exactly. 

T he result of the lookup is a method block. T he method block indicates the type of method 
(native, synchronized, and so on) and the number of arguments (nargs) expected on the 
operand stack. 

I f themethod ismarked synchronized, themonitor associated with thedassisentered. (T helast 
two paragraphs are identical to those in mvokevirtuai, except that no NuiiPointerException 
can be thrown.) 

invokeinterface ..., handle, [argl, arg2, ...] => ... 

I nvokeinterfacemethod. The operand stack must contain a reference (handle) to an object and 
some number of arguments, bytei and byte 2 are used to construct an index into the constant 
pool of the current class. The item at that index in the constant pool contains the complete 
method signature. A pointer to the object's method table is retrieved from theobject reference. 
Themethod signatureislooked up in the method table. Themethod signature is guaranteed 
to exactly match one of themethod signatures in the table. 

T he result of the lookup is a method block. T he method block indicates the type of method 
(native, synchronized, and so on) but, unlike the other "invoke” bytecodes, the number of 
availablearguments(nargs) istaken from byte3; byte4 isreserved for futu reuse. (Thelast three 
paragraphs are identical to those in mvokevirtuai.) 
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Exception Handling 

athrow handle => [undefined] 

T hrow exception, handle must bea handleto an exception object. T hat exception, which must 
beasu bclassofihrowabie,isthrown.ThecurrentJava st ackframeissearchedforthemost recent 
catch clause that handles the exception. If a matching "catch-list" entry isfound, the pc is reset 
to the address indicated by the catch- list pointer, and execution continues there. 

If no appropriate catch clause isfound in the current stack frame, that frame is popped and the 
exception isrethrown, starting the process all over again in the parent frame. Ifhandie isnuii, 
then a NuiiPointerException is thrown instead. 

Miscellaneous Object Operations 

new ... => . . . , handle 

C reate new object, bytei and byte2 are used to construct an index into the constant pool of the 
current class. Theitem at that index should beadassnamethat can be resolved to a class pointer, 
class. A new instanceofthatdassisthen created and areference(handie) fortheinstanceisplaced 
on the top of the stack. 

checkcast ..., handle => ..., [handle]...] 

M ake sure object is of given type, handle must bea reference to an object, bytei and byte2 are 
used to construct an index into the constant pool of the current class. The string at that index 
of the constant pool ispresumedto be adassname that can be resolved to a class pointer, class. 

checkcast determi neswhether handle can becast to a referenceto an object of that class. (A nun 
handle can be cast to any class.) If handle can be legally cast, execution proceeds at the next 
bytecode, and the handle for handle remains on the stack. If not, a ciasscastException is 
thrown. 

instanceof . . . , handle => . . . , result 

Determine whether object isof given type, handle must be a reference to an object, bytei and 
b y te2 areusedto construct an index into theconstant pool ofthecurrentdass.Thestringatthat 
index of the constant pool is presumed to be a class name that can be resolved to a class pointer, 
class. 



Ifhandie iSnull, the result is (false). Otherwise, instanceof determines whether handle can 
be cast to a reference to an object of that class. T he result is i (true) if it can, and 0 (false) 
otherwise. 
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Monitors 

monitorenter . . . , handle => . . . 

Enter monitored region of code, handle must be a reference to an object. The interpreter 
attemptsto obtain exclusive access viaalock mechanism to handle. If anotherthread already has 
handle locked, thecurrentthread waitsuntil thehandie isunlocked. I f the current thread already 
has handle locked, execution continues normally. If handle has no lock on it, this bytecode 
obtains an exclusive lock. 

monitorexit . . . , handle => . . . 

Exit monitored region of code, handle must be a reference to an object. T he lock on handle is 
released. I f this isthe last lock that this thread has on that handle (onethread isallowed to have 
multiple locks on a single handle), other threads that are waiting for handle are allowed to 
proceed. (A nun in either bytecode throws NuiiPointerException.) 

Debugging 

breakpoint -no Change- 

Call breakpoint handler. The breakpoint bytecode is used to overwrite a bytecode to force 
control temporarily back to the debugger prior to the effect of the overwritten bytecode. T he 
original bytecode’s operands (if any) are not overwritten, and the original bytecode is restored 
when the breakpoint bytecode is removed. 

The_quick Bytecodes 

The following discussion, straight out of thejava virtual machine documentation, shows you 
an exampleof thedevernessmentioned earlier that'sneeded to makeabytecodeinterpreterfast: 

The following set of pseudo-bytecodes, suffixed by_quick, are all variants of standard 
J ava bytecodes. T hey are used by the run-time to improve the execution speed of the 
bytecode interpreter. They aren't officially part of the virtual machine specification 
and are invisible outside aj ava virtual machine implementation. However, inside that 
implementation they have proven to bean effective optimization. 

First, you should know that javac still generates only non-_quick bytecodes. Second, 
all bytecodes that have a_quick variant reference the constant pool. W hen _ qu ick 
optimization is turned on, each non-_quick bytecode (that hasa_quick variant) 
resolves the specified item in the constant pool, signals an error if the item in the 
constant pool could not be resolved for some reason, turns itself into the_quick 
variant of itself, and then performs its intended operation. 
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T his is identical to the actions of the non-_quick bytecode, except for the step of 
overwriting itself with its_quick variant. The _quick variant of a bytecode assumes 
that the item in the constant pool has already been resolved, and that this resolution 
did not produce any errors. It simply performs the intended operation on the resolved 
item. 

Thus, as your bytecodes are being interpreted, they are automatically getting faster and faster! 
H ere are all the_quick variants in the current Java run-time: 

ldc1_quick 

ldc2_quick 

ldc2w_quick 

anewarray_quick 

multinewarray_quick 

putfield_quick 

putfield2_quick 

getfield_quick 

getfield2_quick 

putstatic_quick 

putstatic2_quick 

getstatic_quick 

getstatic2_quick 

invokevirtual_quick 
invokevirtualob j ect_quick 
invokenonvirtual_quick 
invokestatic_quick 
invokeinterface_quick 

checkcast_quick 

instanceof_quick 

If you'd like to go back in today’s lesson and look at what each of these does, you can find the 
nameoftheoriginal bytecodeon which a_quick variant isbased by simply removing the_quick 
from its name. The bytecodes putstatic, getstatic, puttieid, and gettieid have two _quick 
variants each, oneforeach stack picture in their original descriptions, invokevirtuai has two 
variants: onefor objects and onefor arrays to do fast lookups in javaia. object). 



Note: One last note on the_quick optimization, regarding the unusual handling of 
the constant pool (for detail fanatics only): 

W hen a class is read in, an array constant_pooi[ ] of size nconstants is created and 
assigned to afield in the class. constant_pooi[ 0 ] is set to point to a dynamically 
allocated array that indicates which fields in theconstant_pooi have already been 
resolved. constant_pool[1 ] through constant_pool[nconstants - 1] are Set to 
point at the "type" field that corresponds to this constant item. 
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I W hen a bytecode is executed that references the constant pool, an index is gener- 
ated, and constant_pooi[0] is checked to see whether the index has already been 
resolved. If so, thevalueof constant_pooi[index] is returned. If not, thevalueof 
constant_pooi [ index ] isresolved to betheactual pointer or data, and overwrites 
whatever val ue was already i n constant_pooi [ index ] . 



The .class File Format 

You won't be given theentire .class file format here, only a taste of what it's like. (You can read 
all about it in the release documentation.) It’s mentioned here because it is one of the parts of 
Javathatneedsto bespecified carefully if all Javaimplementationsareto becompatiblewith one 
another, and ifj ava bytes are expected to travel across arbitrary networks- to and from arbitrary 
computers and operating systems- and yet arrive safely. 

T he rest of this section paraphrases, and extensively condenses, the latest (alpha) release of the 
.class documentation. 

.class files are used to hold the compiled versions of both Java classes and Java interfaces. 
Compliant Java interpreters must be capable of dealing with all .class files that conform to the 
following specification. 

A Java .class file consists of a stream of 8-bit bytes. All 16-bit and 32-bit quantities are 
constructed by reading in two or four 8-bit bytes, respectively. The bytes are joined together in 
big-endian order. (Usejava.io.Datainput and java. lo.Dataoutputto read and writedassfiles.) 

T heclassfileformat is presented below asaseriesof C-struct-likestructures. H owever, unlike 
aC struct, there is no padding or alignment between pieces of the structure, each field of the 
structu remay be of variable size, and an array may beof variablesize(in thiscase, somefield prior 
to the array gives the array’s dimension). The types ut, u2, and u4 represent an unsigned 
one-, two-, or four-byte quantity, respectively. 

Attributes areused at several different placesinthe.dassformat. All attributeshavethefollowing 
format: 

GenericAttribute_info { 
u2 attribute_name; 
u4 attribute_length; 
ul info[attribute_length] ; 

> 

The attribute_name is a 16-bit index into the class’s constant pool; the value of 
constant_pooi [ att ribute_name ] is a string giving the name of the attribute. The field 
attribute_iength gives thelength of thesubsequent information in bytes. This length does not 
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include thefour bytes needed to store attribute_name and attribute_iength. I n thefollowing 
text, whenever an attributeisrequired, namesof all theattributesthat arecurrently understood 
arelisted. I n thefuture, moreattributeswill be added. C I ass file read ers are expected to skip over 
and ignore the information in any attributes that they do not understand. 

Thefollowing pseudo-structure gives a top-level description of the format of a class file: 

ClassFile { 
u4 magic; 
u2 minor_version 
u2 major_version 
u2 constant_pool_count; 

cp_info constant_pool[constant_pool_count - 1]; 

u2 access_flags; 

u2 this_class; 

u2 superclass; 

u2 interfaces_count; 

u2 interfaces[interfaces_count] ; 

u2 fields_count; 

field_info fields [fields_count ] ; 

u2 methods_count; 

method_info methods[methods_count] ; 

u2 attributes_count; 

attribute_inf o attributes [ attribute_count ] ; 



H ere's one of the smaller structures used: 

method_info { 

u2 access_flags; 
u2 name_index; 
u2 signature_index; 
u2 attributes_count; 

attribute_info attributes[attribute_count] ; 



Finally, here’s a sample of one of the later structures in the .class file description: 

Code_attribute { 

u2 attribute_name_index; 
u2 attribute_length; 
ul max_stack; 
ul max_locals; 
u2 code_length; 
ul code[code_length] ; 
u2 exception_table_length; 

{ u2_ start_pc; 

u2_ end_pc; 
u2_ handler_pc; 
u2_ catch_type; 

> exception_table[exception_table_length] ; 
u2 attributes_count; 

attribute_info attributes[attribute_count] ; 
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N one of this is meant to be completely comprehensible (though you might be able to guess at 
what a lot of thestructu re members are for), but just suggestive of thesort of structures that live 
inside, classfiles. Becausethecompilerand run-timesourcesare available, you can always begin 
with them if you actually have to read or write .class files yourself. T hus, you don’t need to have 
a deep understanding of the details, even in that case. 

Method Signatures 

Because method signatures are used in .classfiles, now isan appropriate timeto explore them 
in the detail promised on earlier days- but they’re probably most useful to you when writing 
the native methods of yesterday’s lesson. 

NEW** A signature is a string representing the type of a method, field, or array. 

TERM 

A field signature represents the valueof an argument to a method orthevalueof avariableand 
is a series of bytes in the following grammar: 

<field signature> := <field_type> 

<field type> := <base_type> ] <object_type> ] <array_type> 

<base_type> :=b!C!D|f|I!J!S!z 

<object_type> := L <full.ClassName> ; 

<array_type> := [ <optional_size> <field_type> 

<optional_size> := [0-9]* 

H erearethemeaningsof thebase types: b (byte), c (char), d (double), f (float), i (int), j (long), 
S (short), and Z (boolean). 

A return-type si gnatu re representsthe return valuefrom a method and isa series of bytes in the 
following grammar: 

<return signature> := <field type> | V 

T he character v (void) indicates that the method returns no value. 0 therwise, the signature 
indicates the type of the return value. An argument signature represents an argument passed to 
a method: 

<argument signature> := <field type> 

Finally, amethodsignaturerepresentstheargumentsthatthemethod expects, and thevaluethat 
it returns: 

<method_signature> := (<arguments signature>) <return signature> 

<arguments signature> := <argument signature:** 
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Let’s try out the new rules: a method called compiexMethod ( ) in the class 
my. package. name. compiexciass takes three arguments— a long, a boolean, and a two- 
dimensional array of Shorts- and returnsthis. T hen, (JZ [ [S) Lmy . package . name . compiexciass ; 
is its method signature. 

A method signature is often prefixed by the name of the method, or by its full packagefusing 
an underscored the pi ace of dots) and its class namefollowed by a slash / and thenameof the 
method, to form a complete method signature. (You saw several of these generated in stub 
comments yesterday.) Now, at last, you have the full story! Thus, the following: 

my_package_name_ComplexClass/ compiexMethod (JZ[ [S) Lmy . package . name . Compiexciass; 

is the full, complete method signature of method compiexMethodo. (Phew!) 

The Garbage Collector 

Decades ago, programmers in both the Lisp and the Smalltalk community realized how 
extremely valuable it isto be able to ignore memory deallocation. T hey realized that, although 
allocation is fundamental, deallocation is forced on the programmer by the laziness of the 
system— it should be able to figure out what is no longer useful, and get rid of it. I n relative 
obscurity, these pioneering programmers developed a whole series of garbage collectors to 
perform thisjob, each getting more sophisticated and efficient astheyearswent by. Finally, now 
that the mainstream programming community has begun to recognize the value of this 
automated technique, Java can becomethefirst really widespread application of thetechnology 
those pioneers developed. 



The Problem 



I magine that you’re a programmer in a C-like language (probably not too difficult for you, 
because these languages are the dominant ones right now). Each time you create something, 
anything, dynamically in such a language, you arecompletely responsiblefor tracking thelifeof 
this object throughout your program and mentally deciding when it will be safe to deallocate 
it. T hiscan bequiteadifficult (sometimeimpossible) task, because any of theother libraries or 
methods you’ve called might have "squirreled away” a pointer to the object, unbeknownst to 
you. W hen it becomes impossibleto know, you simply choosene/er to deallocatethe object, or 
at leastto wait until every library and method call involved hascompleted, which could benearly 
as long. 




T he uneasy feeling you get when writing such code is a natural, healthy response to what is 
inherently an unsafeand unreliablestyleof programming. If you havetremendousdiscipline- 
and so does everyone who writes every library and method you call— you can, in principle, 
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su rvivethisresponsibility without too many mishaps. But aren’t you human?Aren'tthey?T here 
must be some small slips in this perfect discipline due to error. What’s worse, such errors are 
virtually undetectable, asanyonewho’stried to hunt down astray pointer problem in C will tell 
you. What about the thousands of programmers who don’t have that sort of discipline? 

Another way to ask this question is: Why should any programmers be forced to have this 
discipline, when it is entirely possible for the system to remove this heavy burden from their 
shoulders? 

Software engineering estimateshave recently shown that for every 55 linesof production C-like 
codein theworld, there is one bug. This meansthat your electric razor has about 80 bugs, and 
your TV, 400. Soon they will have even more, because the size of this kind of embedded 
co m pu ter soft ware i s grow i n g expo n en ti al I y . W h en you begi n to th i n k of h ow m u ch C - 1 i ke cod e 
is in your car’s engine, it should give you pause. 

M any of theseerrorsaredueto themisuseof pointers, by misunderstanding or by accident, and 
to theearly, incorrect freeing of allocated objectsin memory. Java addresses both of these- the 
former, by eliminating explicit pointers from the Java language altogether and the latter, by 
including, in everyjava system, a garbage collector that solves the problem. 

The Solution 

I maginea run-time system that tracks each object you create, notices when the last reference to 
it has vanished, and frees the object for you. H ow could such a thing actually work? 

0 ne brute-force approach, tried early in the days of garbage collecting, is to attach a reference 
counter to every object. W hen the object is created, the counter is set to i . Each time a new 
reference to the object is made, the counter is incremented, and each time such a reference 
disappears, the counter is decremented. Because all such references are controlled by the 
language- as variables and assignments, for example- thecompiler can tell whenever an object 
reference might be created or destroyed, just asit doesin handlingthescoping of local variables, 
and thus it can assist with this task. The system itself "holds onto” a set of root objects that are 
considered too important to be freed. The classobject is one example of such aV.I.P. object. 
(V.I.O .?) Finally, all that's needed is to test, after each decrement, whether the counter has hit 
0. If it has, the object isfreed. 

If you think carefully about this approach, you can soon convince yourself that it isdefinitely 
correct when it decides to free anything. It isso simplethat you can immediately tell that it will 
work. The low- level hacker in you might also feel that if it’sthat simple, it’s probably not fast 
enough to run at the lowest level of the system— and you’d be right. 

Think about all the stack frames, local variables, method arguments, return values, and local 
variables created in the course of even afew hundred millisecondsof a program’s life. For each 
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of these tiny, nano-steps in the program, an extra increment— at best— or decrement, test, and 
deallocation— at worst— will be added to the running time of the program. In fact, the first 
garbage collectors were slow enough that many predicted they could never be used at all! 

Luckily, a wholegeneration of smart programmers has invented a big bag of tricks to solve these 
overhead problems. 0 netrick isto introduce special "transient object” areas that don’t need to 
bereferencecounted.Thebestofthesegenerationalscavenginggarbagecollectorstodaycan take 
lessthan 3 percent of thetotal ti meof your program— a remarkablefeat if you real izethat many 
other language features, such as loop overheads, can be as large or larger! 

There are other problemswith garbage collection. If you are constantly freeing and reclaiming 
space in a program, won’t the heap of objects soon become fragmented, with small holes 
everywhere and no room to create new, largeobjects?Becausethe programmer isnow free from 
the chains of manual deallocation, won’t they create even more objects than usual? 

What’s worse, there isanother way that this simple reference counting scheme is inefficient, in 
space rather than time. If a long chain of object references eventually comes full circle, back to 
thestarting object, each obj ect's reference count remainsat least i forever. N oneoftheseobjects 
will ever be freed! 



T ogether, these problems imply that a good garbage collector must, every once in awhile, step 
back to compact or to clean up wasted memory. 

NEW*- Compaction occurs when a garbage col lector steps back and reorganizes 
TERM memory, eliminating the holes created by fragmentation. Compacting 

memory is simply a matter of repositioning objects one-by-one into a new, 
compact grouping that places them all in a row, leaving all the free memory in the 
heap in one big piece. 



C leaning up the circular garbage still lying around after reference counting is called 
marking and sweeping. A mark-and-sweep of memory involves first marking every root 
object in the system and then following all the object references inside those objects to 
new objects to mark, and so on, recursively. Then, when you have no more references 
to follow, you "sweep away” all the unmarked objects, and compact memory as 
before. 



Thegood newsisthatthissolvesthespaceproblemsyou werehaving.Thebad newsisthatwhen 
thegarbagecollector "steps back" and doestheseoperations, a nontrivial amount of time passes 
duringwhichyourprogramisunableto run— all itsobjectsare being marked, swept, rearranged, 
and so forth, in whatseemslikean uninterruptible procedure. Your first hint to a solution isthe 
word "seems.” 
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Garbage collecting can actually be done a little at a time, between or in parallel with normal 
program execution, thus dividing up the large time needed to "step back” into numerous so- 
small-you-don’t-notice-them chunksof timethat happen between thecracks. (Of course, years 
of smart thinking went into the abstruse algorithms that make all this possible!) 

Onefinal problem that might worry you a little has to do with these object references. Aren't 
these "pointers” scattered throughout your program and not just buried in objects? Even if 
they'reonly in objects, don’t they haveto bechanged whenever theobject they point to ismoved 
bytheseprocedures?Theanswerto both of thesequestionsisaresoundingyes, and overcoming 
them is the final hurdle to making an efficient garbage collector. 

T here are really only two choices. T hefirst, brute force, assumesthat all the memory containing 
object references needs to be searched on a regular basis, and whenever the object references 
found bythissearch match objectsthat have moved, theold referenceischanged.Thisassumes 
that there are "hard" pointers in the heap's memory— ones that point directly to other objects. 
By introducing various kinds of "soft” pointers, including pointers that are like forwarding 
addresses, the algorithm improves greatly. Although these brute-force approaches sound slow, 
it turns out that modern computers can do them fast enough to be useful. 



Note: You might wonder how the brute-force techniques identify object references. 
I n early systems, references were specially tagged with a "pointer bit,” so they could 
be unambiguously located. N ow, so-called conservative garbage collectors simply 
assume that if it looks like an object reference, it is- at least for the purposes of the 
mark and sweep. Later, when actually trying to update it, they can find out 
whether it really is an object reference or not. 



T hefinal approach to handling object references, and theonej ava currently uses, isalso oneof 
the very first ones tried. It involves using 100 percent "soft” pointers. An object reference is 
actually a handle, sometimes call an "OOP,” to the real pointer, and a large object table exists 
to map these handles into the actual object reference. Although this does introduce extra 
overhead on almost every object reference (some of which can be eliminated by clever tricks, as 
you might guess), it’snottoohighapriceto pay for thisincredibly valuable level of indirection. 

This indirection allows the garbage collector, for example, to mark, sweep, move, or examine 
oneobjectatatime. Each object can be independently moved "out from under” a runningj ava 
program by changing only the object table entries. T his not only allows the "step back” phase 
to happen in the tiniest steps, but it makesagarbage collector that runsliterally in parallel with 
your program much easier to write. This is what thej ava garbage collector does. 
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Warning: You need to be very careful about garbage collection when you’re doing 
wQ critical, real-time programs (such as those mentioned yesterday that legitimately 
U require native methods)— but how often will your Java code be flying a commercial 
I airliner in real-time, anyway? 



J ava's Parallel Garbage Collector 

Java applies almost all these advanced techniques to give you a fast, efficient, parallel garbage 
collector. Runningin a separate thread, it cleans up thejava environment of almost all trash (it 
is conservative), silently and in the background, is efficient in both space and time, and never 
steps back for morethan an unnoticeably small amount of time. You should never need to know 
it’s there. 

By the way, if you want to forcea full mark-and-sweep garbage collection to happen soon, you 
candososirnplybycallingthesystem.gco method. You mightwantto do thisif you just freed 
up a majority of theheap'smemory in circular garbage, and want it all taken away quickly. You 
might also call this whenever you’re idle, asa hint to the system about when it would be best to 
come and collect the garbage. T his "meta knowledge” is rarely needed by the system, however. 

Ideally, you’ll never notice thegarbage collector, and all those decades of programmers beating 
their brains out on your behalf will simply let you sleep better at night— and what'swrong with 
that? 



The Security Story 

Speaking of sleeping well at night, if you haven't stepped back yet and said, "You mean Java 
programswill be running rampant on the I nternet!?!” you better do so now, for it isa legitimate 
concern. I n fact, it isoneof themajor technical stumbling blocks(theothers being mostly social 
and economic) to achieving thedream of ubiquity and codesharing mentioned earlier in today’s 
lesson. 

Why You Should Worry 

Any powerful, flexible technology can be abused. As the Net becomes mainstream and 
widespread, it, too, will be abused. Already, there have been many blips on the security radar 
screens of those of us who worry about such things, warning that (at least until today), not 
enough attention has been paid by the computer industry (or themedia) to solving some of the 
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problemsconstructivelythatthisnew world bringswith it. 0 neofthebenefitsof solving security 
once and for all will beaflowering unseen beforein the virtual communities of theN et; whole 
new economiesbased on people’sattention and creativity will springto life, rapidly transforming 
our world in new and positive ways. 

The downside to all this new technology, is that we (or someone!) must worry long and hard 
about how to make the playgroundsof thefutu re safefor our children, and for us. Fortunately, 
J ava is a big part of the answer. 

Why You Might Not Have To 

W hat gives me any confidence that thej ava language and environment will be safe, that it will 
solve the technically dauntiarand extremely thorny problems inherent in any good form of 
security, especially for networks? 

0 nesimplereason isthehistory of thepeople, and thecompany, that created J ava. M any of them 
are the very smart programmers referred to throughout the book, who helped pioneer many of 
theideasthat makej ava great and who have worked hard over the decades to maketechniques 
such as garbage collection a mainstream reality. They are technically capable of tackliarand 
solving the hard problems that need to be solved. In particular, from discussions with Chuck 
M cM anis, oneofjava'ssecuritygurus, I haveconfidencethathehasthoughtthroughthesehard 
problems deeply, and that he knows what needs to be done. 

Sun M icrosystems, the company, has been pushing networks as the central theme of all its 
software for more than a decade. Sun has the engineers and the commitment needed to solve 
these hard problems, because these same problems are at the very center of both its future 
businessand itsvision of thefutu re, in which networking isthecenterof everything— and global 
networks are nearly useless without good security. Just this year, Sun has advanced the state of 
the art in easy-to-use I nternet security with its new SunScreen products, and it has assigned 
W hitfield D iffieto overseethem, who istheman who discovered theunderlying ideason which 
essentially all interestiag forms of modern encryption are based. 

Enough on "deep background.” W hat doesthej ava environment provideright now that helps 
us feel secure? 

J ava's Security Model 

Java protects you against potential "nasty” Java code via a series of interlocking defenses that, 
together, form an imposing barrier to any and all such attacks. 
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" Caution: Of course, no one can protect you from your own ignorance or careless- 
ness. If you’re the kind of person who blindly downloads binary executables from 
^ your I nternet browser and runs them, you need read no further! You are already in 
more danger than J ava will ever pose. 

As a user of this powerful new medium, the I nternet, you should educate yourself to 
the possible threats this new and exciting world entails. In particular, downloading 
"auto running macros" or reading e-mail with "executable attachments" is just as 
much a threat as downloading binaries from the N et and running them. 

j Java does not introduce any new dangers here, but by being the first mainstream use 
of executable and mobile code on the Net, it is responsible for making people 
suddenly aware of the dangers that have always been there. J ava is already, as you 
will soon see, much less dangerous than any of these common activities on the N et, 
and can be made safer still over time. M ost of these other (dangerous) activities can 
never be made safe. So please, do not do them! 

A good rule of thumb on the N et is: D on’t download anything that you plan to 
execute (or that will be automatically executed for you) except from someone (or 
some company) you know well and with whom you’ve had positive, personal 
experience. If you don’t care about losing all the data on your hard drive, or about 
your privacy, you can do anything you like, but for most of us, this rule should be 
| law. 

Fortunately, Java allows you to relax that law. You can run Java applets from 
anyone, anywhere, in complete safety. 



Java’s powerful security mechanismsact at four different levels of the system architecture. First, 
thej ava language itself was designed to be safe, and thej ava compiler ensures that source code 
doesn't violate these safety rules. Second, all bytecodes executed by the run-time are screened 
to be sure that they also obey these rules. (Thislayer guardsagainst having an altered compiler 
produce code that violates the safety rules.) Third, the class loader ensures that classes don’t 
violate name space or access restrictions when they are loaded into the system. Finally, API- 
specific security prevents appletsfrom doing destructivethings. T hisfinal layer dependson the 
security and integrity guarantees from the other three layers. 

Let’s now examine each of these layers in turn. 
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The Language and the Compiler 

Thejava language and its compiler are thefirst line of defense. Java was designed to be a safe 
language. 

M ost other C -like languages have facilities to control access to "objects," but also have ways to 
“forge” accesstoobjectsforto partsof objects), usually by (mis-)using pointers. This introduces 
two fatal security flawsto any system built on these languages. 0 neisthat no object can protect 
itself from outside modification, duplication, or "spoofing” (others pretending to be that 
object). Another isthat a languagewith powerful pointersismorelikely to haveseriousbugsthat 
compromise security. T hese pointer bugs, where a "runaway pointer” starts modifying some 
other object’s memory, were responsible for most of the public (and not-so-public) security 
problems on the I nternet this past decade. 

Javaeliminatesthesethreatsinonestrokeby eliminating pointersfromthelanguage altogether. 
T herearestill pointersof akind — object references- butthesearecarefully controlled to besafe: 
they are unforgeable, and all casts are checked for legality before being allowed. In addition, 
powerful new array facilitiesinjavanot only help to offset the lossof pointers, but add additional 
safety by strictly enforcing array bounds, catching more bugsfor the programmer (bugs that, in 
other languages, might lead to unexpected and, thus, bad-guy-exploitable problems). 

The language definition, and the compilers that enforce it, create a powerful barrier to any 
"nasty” J ava programmer. 

Because an overwhelming majority of the"net-sawy” softwareon thel nternet may soon bej ava, 
itssafelanguagedefinition andcompilershelpto guaranteethatmostofthissoftwarehasasolid, 
secure base. W ith fewer bugs, N et software will be more predictable— a property that thwarts 
attacks. 

Verifying the Bytecodes 

What if that "nasty” programmer gets a little more determined, and rewrites thej ava compiler 
to suit hisnefariouspurposes?TheJ ava run-time, getting the lion'sshare of its bytecodes from 
the N et, can never tell whether those bytecodes were generated by a "trustworthy" compiler. 
Therefore, it must verify that they meet all the safety requirements. 

B efore ru n n i ng any bytecod es, the ru n-ti me su bj ects them to a ri gorou s seri es of tests that vary 
in complexity from simple format checks all the way to running a theorem prover, to make 
certain that they are playing by the rules. T hese tests verify that the bytecodes do not forge 
pointers, violate access restrictions, access objects asother than what they are(inputstream S are 
always used as inputstreams, and never as anything else), call methods with inappropriate 
argument values or types, nor overflow the stack. 
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C onsider the following J ava code sample: 

public class VectorTest { 
public int array [ ] ; 



public int sum() { 

int[] localArray = array; 
int sum = 0; 



for (int i = localArray . length; --i >= 0; ) 

sum += localArray! i] ; 
return sum; 

} 

> 

The bytecodes generated when this code is compiled look something likethe following: 



aload_0 

getfield #10 

astore_l 

iconst_0 

istore_2 

aload_l 

arraylength 

istore_3 

A: iinc 3 -1 

iload_3 

iflt B 

iload_2 

aload_l 

iload_3 



Load this 
Load this .array 
Store in localArray 
Load 0 
Store in sum 
Load localArray 
G ets its length 
Store in i 
Subtract i from i 
Load i 

Exit loop if < 0 
Load sum 
Load localArray 
Load i 



iaload 

iadd 

istore_2 
goto A 
B: iload_2 

ireturn 



Load localArray[i] 
Add sum 
Store in sum 
Do it again 
Load sum 
Return it 
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Note: The excellent examples and descriptions in this section of the book are 
paraphrased from the tremendously informative security paper in the (alpha) Java 
release. I 'd encourage you to read whatever the latest version of this document is in 
newer releases, if you want to follow the ongoing J ava security story. 



Extra Type Information and Requirements 

Java bytecodes encodemoretypeinformation than isstrictly necessary fortheinterpreter. Even 
though, for example, theaioad and iioadopcodesdoexactlythesamething,aioadisalwaysused 
to load an object referenceand uoad used to load an integer. Somebytecodes(such asgetf ieid) 
include a symbol table reference— and that symbol tablehase/en more type information. This 
extra type information allowstherun-timesystem to guarantee that Javaobjects and data aren’t 
illegally manipulated. 

Conceptually, before and after each bytecode is executed, every slot in the stack and every local 
variable has some type. Thiscollection of type information— all the slots and local variables — 
iscalled thetypestateof theexecution environment. An important requirement of thej ava type 
state isthat it must be determinable statically by induction — that is, before any program code 
isexecuted. Asa result, as the run-time systems reads bytecodes, each isrequired to have the 
following inductiveproperty: given only thetype state before theexecution of the bytecode, the 
type state afterward must be fully determined. 

G iven "straight-line" bytecodes (no branches), and starting with a known stack state, the state 
of each slot in the stack is therefore always known. For example, starting with an empty stack: 

iioad_i Load integer variable. Stack type state is i. 

iconst 5 Load integer constant. Stack type state is n. 

iadd Add two integers, producing an integer. Stack type state is i. 



Note: Smalltalk and PostScript bytecodes do not have this restriction. Their more 
dynamic type behavior does create additional flexibility in those systems, but J ava 
needs to provide a secure execution environment. It must therefore know all types 
at all times in order to guarantee a certain level of security. 
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Another requirement made by thej ava run-time is that when a set of bytecodes can take more 
than one path to arrive at the same point, all such paths must arrive there with exactly the same 
type state. T hisisastrict requirement, and implies, for example, that compilers cannot generate 
bytecodesthat load all theelementsofan array onto thestack. (Becauseeachtimethroughsuch 
aloopthestack’stypestatechanges,thestartoftheloop- "the same point" in multiplepaths— 
would have more than one type state, which is not allowed). 



The Verifier 

Bytecodes are checked for compliance with all these requirements, using the extra type 
information in a.dass file, byapart of therun-timecalled theverifier. Itexamines each bytecode 
in turn, constructing the full type state as it goes, and verifies that all the types of parameters, 
arguments, and results are correct. Thus, the verifier acts as a gatekeeper to your run-time 
environment, letting in only those bytecodes that pass muster. 




Warning: Theverifier is the crucial piece of Java’s security, and it depends on your 
having a correctly implemented (no bugs, intentional or otherwise) run-time 
system. As of thiswriting, only Sun is producing Java run-times, and theirs are 
secure. In thefuture, however, you should be careful when downloading or buying 
another company’s (or individual’s) version of thej ava run-time environment. 
Eventually, Sun will implement validation suites for run-times, compilers, and so 
forth to be sure that they are safe and correct. I n the meantime, caveat emptor ! Your 
run-time is the base on which all the rest of Java’s security is built, so make sure it is 
a good, solid, secure base. 



When bytecodes have passed theverifier, they are guaranteed not to: cause any operand stack 
under- or overflows; use parameter, argument, or return types incorrectly; illegally convert data 
from onetypeto another (from an integer to apointer, for example); nor access any object’sfields 
illegally (that is, theverifier checks that the rules for public, private, package, and protected 
are obeyed). 

As an added bonus, because the interpreter can now count on all these facts being true, it can 
run much faster than before. All therequired checksfor safety have been doneup front, so it can 
run at full throttle. I n addition, object referencescan now betreated as capabilities, becausethey 
are unforgeable- capabilities allow, for example, advanced security models for file I/O and 
authentication to be safely built on top of Java. 
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Note: Because you can now trust that a private variable really is private, and that 
no bytecode can perform some magic with casts to extract information from it 
(such as your credit card number), many of the security problems that might arise 
in other, less safe environments simply vanish! These guarantees also make erecting 
barriers against destructive applets possible, and easier. Because thejava system 
doesn’t have to worry about "nasty” bytecodes, it can get on with creating the other 
levels of security it wants to provide to you. 



The Class Loader 

T he class loader is another kind of gatekeeper, albeit a higher-level one. T he verifier was the 
security of last resort. T he class loader is the security of first resort. 

W hen a new dassisloaded into thesystem, it must comefrom oneof several different "realms." 
I n thecurrent release, there are three possible realms: your local computer, thefi rewall-guarded 
local network on which your computer is located, and the I nternet (the global N et). Each of 
these realms is treated differently by the class loader. 



Note: Actually, there can be as many realms as your desired level of security (or 
paranoia) requires. T his is because the class loader is under your control. As a 
programmer, you can make your own class loader that implements your own 
peculiar brand of security. (This is a radical step: you may have to give the users of 
your program a whole bunch of classes- and they give you a whole lot of trust— to 
accomplish this.) 

As a user, you can tell your J ava-aware browser, or J ava system, what realm of 
security (of the three) you’d like it to implement for you right now or from now 
on. 

Asa system administrator, Java has global security policies that you can set up to 
help guide your users to not "giveaway the store” (that is, set all their preferences 
to be unrestricted, promiscuous, "hurt me please!’’). 



In particular, the cl ass loader never allows a cl ass from a "less protected” realm to replaceadass 
from a more protected realm. Thefilesystem’s I/O primitives, about which you should bevery 
worried (and rightly so), are all defined in a local Java class, which meansthat they all live in the 
local-computer realm. T hus, no class from outsideyour computer (from either thesupposedly 
trustworthy local network or from the I nternet) can take the place of these classes and "spoof” 
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J avacodeinto using "nasty” versionsof these primitives. I n addition, dassesin onerealm cannot 
call upon themethodsof dassesin other realms, unlessthosedasseshaveexplicitlydedared those 
methods public. T his implies that classes from other than your local computer cannot even see 
the filesystem I/O methods, much less call them, unless you or the system wants them to. 

I n addition, every new applet loaded from the network is placed into a separate package-like 
namespace. This means that applets are protected even from each other! N o applet can access 
another’s methods (or variables) without its cooperation. Applets from inside the firewall can 
even be treated differently from those outside thefi rewall, if you like. 



Note: Actually, it’s all a little more complex than this. In the current release, an 
applet is in a package "namespace” along with any other applets from that source. 

T his source, or origin, is most often a host (domain name) on the I nternet. T his 
special "subrealm" is used extensively in the next section. Depending on where the 
source is located, outside the firewall (or inside), further restrictions may apply (or 
be removed entirely). This model is likely to be extended in future releases of Java, 
providing an even finer degree of control over which classes get to do what. 



T hedassloader essentially partitionstheworld of J avaclassesinto small, protected littlegroups, 
about which you can safely makeassumptionsthat will alwaysbe true. Thistypeof predictability 
is the key to well-behaved and secure programs. 

You’ve now seen the full lifetime of a method. It starts as source code on some computer, is 
compiled into bytecodes on some (possibly different) computer, and can then travel (asa. class 
file) into any file system or network anywhere in the world. When you run an applet in ajava- 
aware browser (or download a class and run it by hand using j ava), the method's bytecodes are 
extracted from its.classfileand carefully looked overbytheverifier. 0 ncetheyaredeclared safe, 
the interpreter can execute them for you (or a code generator can generate native binary code 
for them using either the "just-in-time” compiler or java2c, and then run that native code 
directly). 

At each stage, more and more security is added. The final level of that security is the Java class 
library itself, which has several carefully designed classes and APIsthatadd thefinal touches to 
the security of the system. 

The Security Manager 

securityManager isan abstract dassthat was recently added to thej ava system to collect, in one 
place, all thesecurity policy decisionsthatthesystem has to makeasbytecodesrun. You learned 
before that you can create your own class loader. I n fact, you may not have to, because you can 
subclass securityManager to perform most of the same customizations. 
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An instance of some subclass of securityManager is always installed as the current security 
manager. It has complete control over which of a well-defined set of "dangerous” methodsare 
allowed to be called by any given class. It takes the real ms from the last section into account, the 
source(origin) of the class, and thetypeof theclass(stand-alone, or loaded by an applet). Each 
of these can be separately configured to have the effect you (the programmer) likeon yourjava 
system. For nonprogrammers, thesystem provides several I evel s of d efau 1 1 secu ri ty pol i ci es from 
which you can choose. 

What is this "well-defined set” of methods that are protected? 

Filel/O isapartoftheset,forobviousreasons. Applets, by default, can open, read, orwritefiles 
only with the express permission of the user— and even then, only in certain restricted 
directories. (Of course, users can always be stupid about this, but that's what system adminis- 
trators are for!) 

Also in this protected set are the methods that create and use network connections, both 
incoming and outgoing. 

T he final members of the set are those methods that allow one thread to access, control, and 
manipulateother threads. (Of course, additional methodscan be protected as well, by creating 
a new subclass of securityManager that handles them.) 

For both file and network access, the user of a J ava-aware browser can choose between three 
realms (and one subrealm) of protection: 

fi: unrestricted (allows applets to do anything) 

G| Irewall (allows applets within thefirewall to do anything) 

□ source (allows applets to do things only with their origin 0 nternet} host, or with other 
applets from there) 

□ local (disallows all file and network access) 

For file access, the source subrealm is not meaningful, so it really has only three realms of 
protection. (Asa programmer, of course, you have full access to the security manager and can 
set up your own peculiar criteria for granting and revoking privilegestoyourheart'scontent.) 

For network access, you can imagine wanting many more realms. For example, you might 
specify different groups of trusted domains (companies), each of which is allowed added 
privileges when applets from that group are loaded. Some groups can be more trusted than 
others, and you might even allow groupsto grow automatically by allowing existing members 
to recommend new members for admission. (The Java seal of approval?) 

In any case, thepossibilitiesareendless, aslongasthereisasecureway of recognizing theoriginal 
creator of an applet. 
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You might think this problem has already been solved, because classes are tagged with their 
origin. I n fact, thej ava run-time goes far out of its way to be sure that that origin information 
isnever lost — anyexecuting method can be dynamically restricted bythisinformation anywhere 
in the call chain. So why isn't this enough? 

Because what you’d really like to be able to do is permanently "tag" an applet with its original 
creator (itstrueori gin), and no matter where it hastraveled, a browser could verify the integrity 
and authenticate the creator of that applet. Just because you don’t know the company or 
individual that operatesaparticular server machinedoesn’t mean that you want to mistrust every 
applet stored on that machine. I t’sjust that, currently, to be really safe, you should mistrust those 
applets, however. 

If somehow those appletswere irrevocably tagged with adigital signature by their creator, and 
that signaturecould also guaranteethat theapplet had not been tampered with, you’d begolden. 



Note: Luckily, Sun is planning to do exactly that for Java, as soon as export 
restrictions can be resolved. 

H ere’s a helpful hint of where the team would like to go, from the security docu- 
mentation: “...a mechanism exists whereby public keys and cryptographic message 
digests can be securely attached to code fragments that not only identify who 
originated the code, but guarantee its integrity as well. This latter mechanism will 
be implemented in future releases." 

Look for these sorts of features in every release of J ava; they will be a key part of the 
future of the Internet! 



0 ne fi nal note about security. D espite the best efforts of thej ava team, there is always a trade- 
off between useful functionality and absolute security. For example, Java applets can create 
windows, an extremely useful capability, buta”nasty" applet could usethisto spoof theuser into 
typing private password information, by showing a familiar program (or operating system) 
window and then asking an expected, legitimate-looking question in it. (The beta release adds 
a special banner to applet-created windows to solve this problem.) 

Flexibility and security can’t both be maximized. Thus far on the Net, people have chosen 
maximum flexibility, and havelived with theminimal security theN et now provides. Let’shope 
that Java can help tip the scales a bit, enabling much better security, while sacrificing only a 
minimal amount of the flexibility that has drawn so many to theN et. 
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Under the Hood 



Summary 

T oday, you learned about the grand vision that someof us havefor Java, and about the exciting 
future it promises. 

Under the hood, theinnerworkingsof the virtual machine, the bytecode interpreter (and all its 
bytecodes), the garbage collector, the class loader, the verifier, the security manager, and the 
powerful security features of Java were all revealed. 

You now know almost enough to writeajavarun-timeenvironmentofyourown— but luckily, 
you don’t have to. You can simply download the latest release of J ava- or use a J ava-aware 
browser to enjoy most of the benefits of J ava right away. 

I hope that Java ends up opening new roads in your mind, as it has in mine. 

Q&A 

Q I'm still a little unclear about why the J ava language and compiler make the N et 
safer. Can’t they just be "side-stepped" by nasty bytecodes? 

A Yes, they can— but don't forget that the whole point of using a safe language and 
compiler was to make the N et as a whole safer as morej ava code is written. An 
overwhelming majority of thisj ava code will be written by "honest" J ava program- 
mers, who will produce safe bytecodes. This makes the N et more predictable ova 
time, and thus more secure. 

Q I know you said that garbage collection is something I don't have to worry 
about, but what if I want (or need) to? 

A So, you are planni ng to fly a plane with J ava. C ool ! F or j ust such cases, thae is a way 
to ask thejava run-time, during startup (java -noasyncgc), not to run garbage 
collation unless forced to, eitha by an explicit call (system. geo) or by running out 
of memory. (Thiscan be quite useful if you have multi pie threads that are messing 
each otha up and want to “get thegc thread out of the way" while testing them.) 
Don’t forget that turning garbage collation off means that any objat you create will 
live a long, longtime. If you're real-time, you neva want to "step back” for a full gc— 
so be sure to reuse objats often, and don't create too many of them! 

Q I like the control above; is there anything else I can do to the garbage collector? 

A You can also force the tinaiizeo methods of any raently freed objats to be called 
immediately via system. runFinaiizationo. You might want to do this if you’re about 
to ask for some resources that you suspat might still be tied up by objats that are 
"gone but not forgotten" (waiting for finalize ( ) ). T his is even rara than starting a gc 
by hand, but it’s mentioned here for completeness. 
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Q W hat's the last word on J ava? 

A J ava adds much more than it can ever take away. 1 1 has always done so for me, and 
now, I hope it will for you, as well. 

The future of the Net is filled with as-yet-undreamt horizons, and the road is long and 
hard, but Java is a great traveling companion. 





Language Summary 



T hisappendixcontainsasummary or quick referenceforthejavalanguage, asdescribed in this 
book. 



T echnical N ote: T his is not a grammar overview, nor is it a technical overview of 
the language itself. It’s a quick reference to be used after you already know the 
basics of how the language works. Ifyou need a technical description of the 
language, your best bet is to visit the] ava Web Site (http://java.sun.com) and 
download the actual specification, which includes a full BN F grammar. 



Languagekeywordsand symbolsareshown in a monospacefont. Arguments and other partsto 
be substituted are in italic monospace. 

0 ptional parts are indicated by brackets (except in thearray syntax section). If there are several 
options that are mutually exclusive, they are shown separated by pipes ([ u) like this: 

[ public | private j protected ] type varname 

Reserved Words 

T he followi ng words are reserved for use by thej ava language itself (some of them are reserved 
but not currently used). You cannot use these words to refer to classes, methods, or variable 
names: 



abstract 


do 


implements 


package 


throw 


boolean 


double 


import 


private 


throws 


break 


else 


inner 


protected 


transient 


byte 


extends 


instanceof 


public 


try 


case 


final 


int 


rest 


var 


cast 


finally 


interface 


return 


void 


catch 


float 


long 


short 


volatile 


char 


for 


native 


static 


while 


class 


future 


new 


sure 




const 


generic 


null 


switch 




continue 


goto 


operator 


synchronized 




default 


if 


outer 


this 





Comments 



/* this is a multiline comment 
// this is a single-line 
/** Javadoc comment */ 



Literals 

number 

number [1 [ J ] L ] 

Qxhex 

OXhex 

Ooctal 

[ number ] . number 
number [ f [ ] ] f ] 
number[ d [|] D] 

[ + [ | ] - ] number 
numberenumber 
numberEnumber 
'character' 
“characters " 

\b 

\t 

\n 

\f 



\\ 

\UNNNN 

false 



comment 



T ype int 
T ype long 
H ex integer 
H ex integer 
Octal integer 
Type double 
T ype float 
T ype double 

Signed 
Exponent 
Exponent 
Single character 
String 

Empty string 

Backspace 

Tab 

Linefeed 
Form feed 
Carriage return 
Double quote 
Single quote 
Backslash 

U nicode escape (nnnn is hex) 

Boolean 

Boolean 
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Variable D eclaration 

[ byte | short ] int | long ] varname 

[ float | double ] varname 

char varname - , 

boolean varname 

classname varname ; 

interfacename varname 

type varname, varname, varname; 



Integers (pick one type) 
Floats (pick one type) 

C haracters 
Boolean 
Class types 
Interface types 
M ulti pie variables 



T he following options are available only for class and instance variables. Any of these options 
can be used with a variable declaration 



[ static ] variableDeclaration 
[ final ] variableDeclaration 

[ public | private | protected ] variableDeclaration 
[volatile] varname 

[transient] varname 



Class variable 
Constants 
Access control 
M odified asynchro- 
nously 

N ot persistent 
(not yet implemented) 



Variable Assignment 



variable = value 
variable++ 
++variable 
variable— 

— variable 
variable += value 
variable -= value 
variable *= value 
variable += value 
variable %= value 
variable &= value 
variable j = value 



Assignment 
postfix I ncrement 
Prefix Increment 
Postfix D ecrement 
Prefix D ecrement 
Add and assign 
Subtract and assign 
M ultiply and assign 
Divide and assign 
M odulusand assign 
and and assign 
or and assign 



variable '= value 



variable ~= value 
variable «= value 


xor and assign 
Left-shift and assign 


variable »= value 


Right-shift and assign 


variable »>= value 


Zero-fill right-shift and assign 


Operators 




arg + arg 


Addition 


arg - arg 


Subtraction 


arg * arg 


M ultiplication 


arg 4- arg 


Division 


arg % arg 


M odulus 


arg < arg 


Less than 


arg > arg 


G reater than 


arg < arg 


Less than or equal to 


arg > arg 


G reater than or equal to 


arg == arg 
arg ^ arg 


Equal 
N ot equal 


arg && arg 


Logical and 


arg \ ] arg 


Logical or 


! arg 


Logical not 


arg & arg 


AND 


arg \ arg 


OR 


arg A arg 


XOR 


arg « arg 


Left-shift 


arg » arg 


Right-shift 


arg »> arg 


Zero-fill right-shift 


~ arg 


Complement 


( type) thing 


Casting 


arg instanceof class 


1 n stance of 



test ? trueop : faiseop T enary (if) operator 
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Objects 



new class () 

new class (arg, arg, arg . . .) 
object .variable 
object .classvar 
Class. classvar 



Create new instance 
N ew instance with parameters 
Instance variable 
Class variable 
Class variable 



object. method () 

obj ect .method (arg , arg , arg . . .) 

object.classmethod() 

object .classmethod (arg , arg , arg . . .) 

Class . classmethod ( ) 

Class. classmethod (arg, arg, arg. . . ) 



I nstance method (no args) 
I nstance method 
Classmethod (no args) 
Classmethod 
Classmethod (no args) 
Classmethod 



Arrays 



N ote: T he brackets in this section are parts of the array creation or access 
statements. T hey do not denote optional parts as they do in other parts of this 
appendix. 



type varnamel ] 
type [ ] varname 
new type[numElements] 
arraylindex] 
array. length 



Array variable 
Array variable 
N ew array object 
Element access 
Length of array 



Loops and Conditionals 

it ( test) block Conditional 

if ( test ) block 
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else block 


Conditional with else 


switch (test) { 

case value : statement 
case value : statement 

default : statement 

> 


switch (only with integer or char types) 


for (initializer , test, change ) block 


for loop 


while ( test ) block 


while loop 


do block 
while (test) 


do loop 


break [ label ] 


break from loop Or switch 


continue [ label ] 


continue loops 


label: 


Labeled loops 


Class Definitions 

class classname block 


Simple Class definition 



Any of the following optional modifiers can be added to the class definition: 

[ final ] class classname block C annot be Subclassed 

[ abstract ] class classname block C annot be instantiated 

[ public ] class classname block Accessible outside 

package 

class classname [ extends Superclass ] block D efine superclass 

class classname [ implements interfaces ] block I mplement One Or more 

interfaces 

Method and Constructor Definitions 

The basic method looks like this, where return Type is a type name, a class name, or void. 
returnType methodName() block Basic method 

returnType methodName (parameter, parameter, ...) block M ethod with parameters 
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M ethod parameters look like this: 

type parameterName 



M ethod variations can indudeany of thefollowing optional keywords: 



[ abstract ] returnType methodName () block 
[ static ] returnType methodName () block 
[ native ] returnType methodName () block 
[ final ] returnType methodName () block 
[ synchronized ] returnType methodName () block 

[ public ] private | protected ] returnType methodName ( ) 



Abstract method 
Class method 
N ative method 

final method 

Thread lock before 
executing 

Block access control 



Constructors look like this: 

classnameO block 

classname (parameter , parameter, parameter...) block 
[ public | private | protected] classname ()block 



basic constructor 
constructor with 
parameters 
Access control 



I n the method/constructor body you can use these references and methods: 



this 

super 

super .methodName ( ) 
this) . . . ) 
super] . . . ) 
return [ value ] 



Refers to current object 
Refers to superclass 
Call a superclass’s method 
Calls class’s constructor 
C alls superclass’s constructor 
Returns a value 



Packages, Interfaces, and Importing 

import package . ciassName I mports specific class name 

import package.* I mports all public classes in 

package 
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package packagename 



Classesin this file belong 
to this package 




interface interfaceName [ extends anotherlnterface ] block 
[ public ] interface interfaceName block 
[ abstract ] interface interfaceName block 



Exceptions and Guarding 

synchronized ( object ) block Waitsfor lock On Object 



try block 


G uarded statements 


catch ( exception ) block 
[ finally block ] 


Executed if exception isthrown 
Cleanup code 


try block 

[ catch ( exception ) block ] 
finally block 


Same as previous example (can 
use optional catch or finally, 
but not both) 





Class Hierarchy 
D iagrams 



by Charles L. Perkins 



C lass H ierarchy D iagrams 



java. applet 
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C lass H ierarchy D iagrams 




java.lanj-exceptions 





C lass H ierarchy D iagrams 




uso 
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C lass H ierarchy D iagrams 
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C lass H ierarchy D iagrams 
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C lass H ierarchy D iagrams 
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About T hese D iagrams 

Thediagramsin thisappendix are class hierarchy diagramsfor the package java and for all the 
subpackages recursively below it in the J ava beta binary release. 



Each page contains the class hierarchy for one package (or a subtree of a particularly large 
package) with all its interfaces included, and each class in this tree is shown attached to its 
superclasses, even if they are on another page. A detailed key is located on the first page of this 
appendix. 



N ote: win 32 Process and uNixprocess appear in their respective distributions of 
Java, but both implement (essentially) the same protocol as their common abstract 
superclass- process— so only it was included. T his means that are no platform- 
dependent classes in the diagrams. (Of course, each release actually has some such 
classes in its .class directories.) Several abstract classes have no subclasses in the 
documented library, but any concrete implementation of Java would define 
subclasses of them. 



I supplemented the (incomplete) API documentation by looking through all the source files 
(below src/java) to find all the (missing) package classes and their relationships. 

I 'veheardtherearevariousprogramsthat auto-layout hierarchiesforyou, but I did thesetheold- 
fashioned way (in other words, I earned it, asj .H . used to say). 0 ne nice side effect isthat these 
diagramsshould bemorereadablethan acomputerwould produce, though you will have to live 
with myaestheticchoices(sorry). I chose, for example, to attach linesthroughthecenterofeach 
class node, something which I think looksand feels better overall (to me) but which on occasion 
can be a little confusing. Follow lines through the center of the classes (not at the corners, nor 
along any line not passing through the center) to connect the dots mentally. 





The Java Class 
Library 



by Laura Lemay 



The J ava Class Library 



T hisappendix provides a general overview of the classes available in thestandard J ava packages 
(that is, the classes that are guaranteed to be available in any Java implementation). This 
appendixisintended for general reference; for moreinformation about dassinheritanceand the 
exceptions defined for each package, seeAppendixB. For more specific information about each 
variable and the methods within each class, seetheAPI documentation from Sun at http:// 

java.sun.com. 



java.lang 

The java. iang packagecontainsthedassesand interfaces that makeup the corejava language. 



I nterfaces 

Runnable 



Classes 



Character 

Class 

ClassLoader 

Double 

Float 

Integer 

Long 

Math 

Number 

Object 

Process 

Runtime 

SecurityManager 

String 

StringBuffer 

System 



M ethodsfor classes that want to run as threads 



0 bject wrapper for boolean values 

0 bject wrapper for char values 

Run-time representations of classes 

Abstract behavior for handling loading of classes 

0 bject wrapper for double values 

0 bject wrapper for float values 

0 bject wrapper for mt values 

0 bject wrapper for long values 

Utility class for math operations 

Abstract superclass of all number classes (integer, 

Float, and so on) 

Generic object class, at top of inheritance hierarchy 

Abstract behavior for processes such as those spawned 

using methods in the system class 

Access to thej ava run-time 

Abstract behavior for implementing security policies 

Character strings 

M utable strings 

Access to Java’s system-level behavior, provided in a 
platform-independent way 
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Thread 



M ethodsfor managing threads and classes that run in 
threads 

ThreadGroup A group of threads 

Throwabie Generic Exception class; all objects thrown must be a 

Throwable 



java, util 

The java. utu package contains various utility classes and interfaces, including random 
numbers, system properties, and other useful classes. 



I nter faces 

Enumeration M ethodsfor enumerating sets of values 

Observer M ethodsfor allowing classes to observe observable 

objects 



Classes 

Bitset A set of bits 

Date T he current system date, as well as methods for 

generating and parsing dates 

Dictionary An abstract class that maps between keys and values 

(superclass Of HashTable) 

Hashtabie A hash table 

observable An abstract class for observable objects 

properties A hashtabie that contains behavior for setting and 

retrieving persistent properties of the system or of a 
class 



Random U tilitiesfor generating random numbers 

stack A stack (a last-in-first-out queue) 

stringTokenizer U tilitiesfor splitting strings into a sequence of 

individual "tokens" 

A growable array of obj ects 



Vector 
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java.io 

The java.io package provides input and output classes and interfaces for streams and files. 



I nter faces 

Datalnput 
D ataO utput 
FilenameFilter 



M ethods for reading machine-independent typed 
input streams 

M ethods for writing machine-independent typed 
output streams 

M ethodsfor filtering file names 



Classes 

BufferedlnputStream 
Buff eredOutputSt ream 
ByteAr ray InputSt ream 
ByteArrayOutputStream 
DatalnputStream 



DataOutputStream 



File 

FilelnputStream 

FileOutputStream 

FilterlnputStream 



FilterOutputStream 



InputStream 



A buffered input stream 
A buffered output stream 
An input stream from a byte array 
An output stream to a byte array 
Enables you to read primitivej ava types 
(ints, chars, booleans, and so on) from a 
stream in a machine-independent way 
Enables you to write primitivej ava data 
types (ints, chars, booleans, and so on) to a 
stream in a machine-independent way 
Represents a file on the host’s file system 
An input stream from a file, constructed 
usi ng a fi lename or descri ptor 
An output stream to a file, constructed using 
a filename or descriptor 
Abstract class which provides a filter for 
input streams (and for adding stream 
functionality such as buffering) 

Abstract class which provides a filter for 
output streams (and for adding stream 
functionality such as buffering) 

An abstract class representing an input 
stream of bytes; the parent of all input 
streams in this package 
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LineNumberlnputStream 

OutputStream 

PipedlnputStream 

PipedOutputStream 

PrintStream 

PushbacklnputStream 

RandomAccessFile 

SequencelnputStream 

StreamTokenizer 

StringBufferlnputStream 



An input stream that keeps track of line 
numbers 

An abstract class representing an output 
stream of bytes; the parent of all output 
streams in this package 
A piped input stream, which should be 
connected to a pipedoutputstream to be 
useful 

A piped output stream, which should be 
connected to a PipedlnputStream to be 
useful (together they provide safe communi- 
cation between threads) 

An output stream for printing (used by 

System. out. println( . . . )) 

An input stream with a 1-byte push back 
buffer 

Provides random-access to a file, constructed 
from filenames, descriptors, or objects 
C onverts a sequence of input streams into a 
single input steam 

Converts an input stream into a sequence of 
individual tokens 

An input stream from astringBufter object 



java.net 

Thejava.net package contains classes and interfaces for performing network operations, such 
as sockets and URLs. 

I nter faces 

ContentH andlerFactory M ethodsfor creating contentHandier objects 

Socketl mpIFactory M ethodsfor creating socket implementa- 

tions (instance of the socketimpi class) 

U RLStreamFI andlerFactory M ethodsfor creating uRLstreamHandier 

objects 
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Classes 

ContentHandler 



inetAddress 

ServerSocket 

Socket 

Socketlmpl 

URL 

URLConnection 

URLStreamHandler 



Abstract behavior for reading data from a U RL 
connection and constructing the appropriate local 
object, based on M IM E types 
An object representation of an I nternet host (host 
name, IP address) 

A server-side socket 
A socket 

An abstract class for specific socket implementations 
An object representation of a U RL 
Abstract behavior for a socket that can handle various 
Web-based protocols (http, ftp, and so on) 

Abstract class for managing streams to object refer- 
enced by URLs 



java.awt 

T he java, awt package containsthedasses and interfacesthat makeup theAbstractW indowing 
T oolkit. 



I nterfaces 

LayoutManager 

MenuContainer 



Classes 

BorderLayout 

Button 

Canvas 

CardLayout 

Checkbox 

CheckboxGroup 

CheckboxMenuItem 



M ethodsfor laying out containers 
M ethodsfor menu-rdated containers 



A layout manager for arranging items in border 

formation 

A U I pushbutton 

A canvas for drawing and performing other graphics 
operations 

A layout manager for H yperC ard-like metaphors 
A checkbox 

A group of exclusive checkboxes (radio buttons) 

A toggle menu item 
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Choice 

Color 

Component 

Container 

Dialog 

Dimension 

Event 

FileDialog 

FlowLayout 

Font 

FontMetrics 



Graphics 

GridBagConstraints 

GridBagLayout 



GridLayout 

Image 

Insets 



Label 

List 

MediaTracker 






A popup menu of choices 
An abstract representation of a color 
T he abstract generic classfor all Ul components 
Abstract behavior for a component that can hold 
other components or containers 
A window for brief interactions with users 
Width and height 

An object representing events caused by the system or 
based on user input 

A dialog for getting file names from the local file 
system 

A layout manager that lays out objects from left to 
right in rows 

An abstract representation of a font 
Abstract classfor holding information about a specific 
font’s character shapes and height and width infor- 
mation 

A top-level window with a title 
Abstract behavior for representing a graphics context, 
and for drawing and painting shapes and objects 
Constraints for components laid out using 

GridBagLayout 

A layout manager that aligns components horizon- 
tally and vertically based on their values from 

GridBagConstraints 

A layout manager with rows and columns; elements 
are added to each cell in the grid 
An abstract representation of a bitmap image 
Distances from the outer border of the window; used 
to lay out components 
A text label for U I components 
A scrolling list 

A way to keep track of the status of media objects 
being loaded over the net 
A menu, which can contain menu items and is a 
container on a menubar 
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MenuBar 

MenuComponent 

Menultem 

Panel 

Point 

Polygon 

Rectangle 

Scrollbar 
Text Area 
TextComponent 
TextField 
Toolkit 

Window 



A menubar (container for menus) 

The abstract superclass of all menu elements 
An individual menu item 
A container that is displayed 
x and y coordinates 
A set of points 

x and y coordinates for the top corner, plus width and 
height 

A Ul scrollbar object 
A multiline, scrollable, editable text field 
T he superclass of all editable text components 
A fixed-size editable text field 
Abstract behavior for binding the abstract AWT 
classes to a platform-specific toolkit implementation 
A top-level window, and the superclass of the Frame 
and Dialog classes 



java.awt.image 

T he j ava . awt . image package is a subpackage of the AW T that provides classes for managi ng 
bitmap images. 



I nterfaces 

ImageConsumer 

imageObserver 

imageProducer 

Classes 

ColorModel 

CropImageFilter 

DirectColorModel 



M ethods for receiving image data created by an 

ImageProducer 

M ethods to track the loading and construction of an 
image 

M ethods to construct or filter image data 



An abstract class for managing color information for 
images 

A filter for cropping images to a particular size 
A specific color model for managing and translating 
pixel color values 



FilteredlmageSource 


An imageproducer that takes an image and an 
ImageFilter object and produces an image for an 

imageConsumer 


ImageFilter 


A filter that takes image data from an imageproducer, 
modifies it in someway, and hands it off to a 

ImageConsumer 


indexColorModel 


A specific color model for managing and translating 
color values in a fixed-color map 


MemorylmageSource 


An image producer that gets its image from memory; 
used to construct an image by hand 


RGBlmageFilter 


Abstract behavior for a filter that modifies the RGB 
values of pixels in RGB images 



java. awt. peer 

The java. awt. peer package is a subpackage of AWT that provides the (hidden) platform- 
specific AWT classes (for example, for M otif, M acintosh, or Windows 95) with platform- 
independent interfaces to implement. Thus, callers using these interfaces need not know which 
platform’s window system these hidden AWT classes are currently implementing. 

EachdassintheAWT that inheritsfrom either component orMenucomponenthasacorresponding 
peer class. Each of those classes is the name of the component with -peer added (for example, 
Buttonpeer, DiaiogPeer, and windowPeer). Because each oneprovides similar behavior, they are 
not enumerated here. 

java. applet 

T he j ava . applet package provides applet-specific behavior. 



1 nter faces 




AppletContext 

AppletStub 

AudioClip 


M ethodsto refer to the applet’s context 
M ethodsfor nonbrowser applet viewers 
M ethodsfor playing audio files 


Classes 




Applet 


The base applet class 
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How Java Differs from C and C++ 



T hisappendixcontainsadescription of most of themajor differences between C , C ++, and the 
Java language. If you area programmer familiar with either C or C++, you may want to review 
thisappendixto catch someofthecommonmistakesandassumptionsprogrammersmakewhen 
using Java. 

Pointers 

Java does not have an explicit pointer type. Instead of pointers, all references to objects — 
including variable assignments, arguments passed into methods, and array elements- are 
accomplished by usingimplicit references. Ref erencesand pointersareessentiallythesamething 
except that you can’t do pointer arithmetic on references (nor do you need to). 

Referencesemanticsalsoenablestructuressuchaslinkedliststo becreated easily in Javawithout 
explicit pointers; merely create a linked list node with variables that point to the next and the 
previous node. Then, to insert items in the list, assign those variables to other node objects. 

Arrays 

Arrays i n J ava arefi rst class objects, and referencesto arrays and their contents are accompl i shed 
through explicit references rather than via point arithmetic. Array boundaries are strictly 
enforced; attempting to read past the ends of an array is a compile or run-time error. As with 
other objects, passing an array to a method passes a reference to theoriginal array, so changing 
the contents of that array reference changes the original array object. 

Arrays of objects are arrays of references that are not automatically initialized to contain actual 
objects. U sing thefollowingj ava codeproduces an array of typewiyobj ect with ten elements, but 
that array initially contains only nulls: 

MyObject arrayofobjs[ ] = new MyOb j ect [10]; 

You must now add actual Myobject objects to that array: 

for (int i; i< arrayofobjs. length. i++) { 
arrayofobjs[i] = new MyObject(); 

J ava doesnot support multidimensional arraysasin C and C++. In Java, you mustcreatearrays 
that contain other arrays. 

Strings 

Strings in C and C ++ are arrays of characters, terminated by a null character (\o). T o operate 
on and manage strings, you treat them as you would any other array, with all the inherent 
difficulties of keeping track of pointer arithmetic and being careful not to stray off the end of 
the array. 
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Strings in Java are objects, and all methods that operate on strings can treat the string as a 
complete entity. Strings are not terminated byanull, nor can you accidentally overstep the end 
of a string (like arrays, string boundaries are strictly enforced). 

Memory Management 

All memory management in Java is automatic; memory is allocated automatically when an 
object iscreated, and arun-timegarbagecollector (the"G C ") freesthat memory when theobject 
is no longer in use. C’smaiioc and tree functions do not exist in Java. 

T o "force” an object to be freed, remove all references to that object (assign variables holding 
it to null, remove it from arrays, and so on). The next time the J ava GC runs, that object is 
reclaimed. 

Data Types 

As mentioned in the early part of this book, all J ava primitive data types (char, mt, long, and 
so on) have consistent sizes and behavior across platforms and operating systems. There are no 
unsigned data types as in C and C++ (except for char, which is a 16-bit unsigned integer). 

Theboolean primitive data type can have two values: true or false. Boolean isnot an integer, 
nor can it be treated as one, although you cannot cast 0 or 1 (integers) to boolean types in J ava. 

C omposite data types are accomplished in J ava exclusively through the use of class definitions. 
The struct, union, and typedet keywords have all been removed in favor of classes. 

C asting between datatypesismuch more controlled in J ava; automaticcastingoccursonly when 
there will be no loss of information. All other casts must be explicit. T he primitive data types 
(mt, float, long, char, boolean, and so on) cannot be cast to objects or vice versa; there are 
methods and special "wrapper” classes to convert values between objects and primitive types. 

Operators 

0 perator precedence and association behaves as it does in C . N ote, however, that the new 
keyword (for creating a new object) binds tighter than dot notation (.), which is different 
behavior from C++. In particular, note the following expression: 

new foo() .bar; 

This expression operates as if it were written likethis: 

(new foo()) .bar; 

0 perator overloading, asin C ++, cannot beaccomplished in Java. The, operator of C hasbeen 
deleted. 
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The»> operator producesan unsigned logical right shift (remember, thereareno unsigned data 
types). 

T he + operator can be used to concatenate strings. 

Control Flow 

Although the it, while, tor, and do statements in J ava are syntactically the same as they are in 
C and C ++, thereisonesignificant difference. Thetest expression for each control flow construct 
must return an actual boolean value (true or false). I n C and C ++, the expression can return 
an integer. 

Arguments 

J ava does not support mechanismsfor optional arguments or for variable-length argument lists 
to functionsasin C and C ++. All method definitionsmust haveaspecific number of arguments. 

C ommand-lineargumentsin J avabehavedifferentlyfrom thosein C and C ++. T hefirst element 
in theargument vector (argv[0]) in C and C++ is the name of the program itself; injava, that 
first argument isthefirst of theadditional arguments. In other words, injava,argv[0] isargvm 
in C and C ++; there is no way to get hold of the actual name of thej ava program. 

Other D ifferences 

The following other minor differences from C and C++ exist injava: 

Z J ava does not have a preprocessor, and as such, does not have #def ines or macros. 
Constants can be created by using the final modifier when declaring class and instance 
variables. 

□ J ava does not have template classes as in C ++. 

II J ava does not include C ’s const keyword or the ability to pass by const reference 
explicitly. 

Z J ava classes are singly inherited, with some multiple-inheritance features provided 
through interfaces. 

All functions are implemented as methods. T here are no functions that are not tied to 
classes. 

Z T he goto keyword does not exist in J ava (it’s a reserved word, but currently 

unimplemented). You can, however, use labeled breaks and continues to break out of 
and continue executing complex switch or loop constructs. 
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